FreeRADIUS Docker镜像文档

镜像概述和主要用途

FreeRADIUS服务器项目是一款高性能、高可配置的多协议策略服务器，支持RADIUS、DHCPv4和VMPS协议。通过RADIUS协议可实现网络认证与授权的集中化管理，大幅减少添加或删除网络用户时的配置变更工作量。

FreeRADIUS可用于802.1x（WiFi）、拨号、PPPoE、***、VoIP等系统的用户认证，支持MySQL、PostgreSQL、Oracle、Microsoft Active Directory、Redis、OpenLDAP等后端数据库。它每天为数亿用户提供互联网访问认证服务，应用场景覆盖从10用户到1000万+用户的各类网络环境。

***：FreeRADIUS

核心功能和特性

• 多协议支持：原生支持RADIUS、DHCPv4和VMPS协议，满足多样化网络策略需求
• 后端集成：兼容多种数据库和目录服务，包括MySQL、PostgreSQL、Active Directory、Redis、OpenLDAP等
• 高性能架构：支持大规模并发认证请求，可处理从百万到数亿用户规模的访问需求
• 高度可配置：灵活的策略规则和模块化设计，适应不同网络环境的定制化需求
• 广泛适用性：适用于WiFi、***、ISP接入、企业网络等多种场景的认证授权管理

使用场景和适用范围

• 企业网络：802.1x WiFi接入认证、***远程访问授权
• 服务提供商：PPPoE拨号认证、宽带接入管理（支持千万级用户）
• 通信系统：VoIP服务用户身份验证、IP PBX接入控制
• 教育机构：校园网访问权限集中管理
• 大型网络：运营商级网络（数亿用户）的互联网访问认证

使用方法和配置说明

启动服务器

默认镜像仅包含基础FreeRADIUS配置，无用户信息，仅接受127.0.0.1的测试客户端连接。生产环境使用前，必须至少添加客户端配置（clients.conf）和用户信息（mods-config/files/authorize），否则容器将拒绝响应任何请求。

启动默认容器：

$ docker run --name my-radius -d freeradius/freeradius-server

定义本地配置

创建基于***镜像的自定义Dockerfile，复制本地配置文件：

FROM freeradius/freeradius-server:latest
COPY raddb/ /etc/raddb/

raddb目录建议包含以下关键文件结构：

clients.conf           # 客户端定义
mods-config/
mods-config/files/
mods-config/files/authorize  # 用户认证信息

客户端配置示例（clients.conf）：

client dockernet {
	ipaddr = 172.17.0.0/16  # 允许访问的客户端IP段
	secret = testing123      # 共享密钥
}

用户配置示例（mods-config/files/authorize）：

bob	Cleartext-Password := "test"  # 用户名bob，密码test

构建本地镜像：

$ docker build -t my-radius-image -f Dockerfile .

使用本地配置

运行容器

启动包含自定义配置的容器，需映射RADIUS服务端口（通常1812/udp用于认证，1813/udp用于记账）：

docker run --rm -d --name my-radius -p 1812-1813:1812-1813/udp my-radius-image

测试认证

使用radtest工具发送测试认证请求（需先安装FreeRADIUS客户端工具包）：

$ radtest bob test 127.0.0.1 0 testing123

成功认证将返回"Access-Accept"响应。停止容器：

docker stop my-radius

运行在调试模式

建议在部署前使用调试模式测试配置，添加-X选项启用详细日志输出。彩色日志需配合-t参数（分配伪终端）：

$ docker run --rm --name my-radius -t -p 1812-1813:1812-1813/udp freeradius/freeradius-server -X

调试输出解读指南参见FreeRADIUS Wiki。

安全注意事项

• 证书替换：镜像中包含的自签名证书仅用于测试，生产环境必须替换为可信CA签发的证书，详见raddb/certs/README.md
• 配置安全：客户端密钥（secret）和用户密码需使用强加密策略，避免明文存储
• 网络隔离：限制容器网络访问权限，仅开放必要端口给授权客户端

调试工具支持

默认Docker环境下使用gdb等调试工具可能因权限限制失败，需添加--privileged标志恢复Linux capabilities：

$ docker run --privileged --rm --name my-radius-debug -t freeradius/freeradius-server -X

镜像变体

freeradius/freeradius-server:<version>

默认生产级镜像，基于Ubuntu Linux构建，包含完整模块和依赖库，适用于大多数部署场景。

freeradius/freeradius-server:<version>-alpine

轻量级镜像，基于Alpine Linux，体积显著小于Ubuntu版本。注意：为最小化镜像体积，此变体不包含所有模块的依赖库（尤其是Perl、Python等语言模块），如需使用这些功能，需在自定义Dockerfile中通过apk add安装相应依赖。

构建Docker镜像

源码中的Dockerfile

FreeRADIUS源码仓库包含多种Linux发行版的Dockerfile模板，位于freeradius-server/scripts/docker/<os_name>（将<os_name>替换为具体发行版名称）。

基础构建命令

$ cd scripts/docker/<os_name>  # 进入目标发行版的Dockerfile目录
$ docker build . -t freeradius-<os_name>  # 构建镜像

构建过程会自动完成：基础镜像拉取、依赖安装、源码克隆和服务器编译。构建完成后可通过docker images查看结果：

$ docker images
REPOSITORY           TAG            IMAGE ID            CREATED             SIZE
freeradius-ubuntu16  latest         289b3c7aca94        4 minutes ago       218MB
freeradius-alpine    latest         d7fb3041bea2        2 hours ago         88.6MB

构建参数

Dockerfile支持通过--build-arg指定构建参数：

• source：Git仓库URL（默认使用***仓库）
• release：Git提交哈希或标签（指定构建版本）

示例：从特定版本构建

$ docker build . \
  --build-arg=release=v3.0.x \
  --build-arg=source=[***] \
  -t freeradius-custom