freeradius/freeradius-dev

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），否则容器将拒绝响应任何请求。

启动默认容器：

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

定义本地配置

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

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

构建本地镜像：

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

使用本地配置

运行容器

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

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

测试认证

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

console
$ radtest bob test 127.0.0.1 0 testing123

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

console
docker stop my-radius

运行在调试模式

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

console
$ 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：

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

镜像变体

freeradius/freeradius-server:<version>

默认生产级镜像，基于https://hub.docker.com/_/ubuntu/%E6%9E%84%E5%BB%BA%EF%BC%8C%E5%8C%85%E5%90%AB%E5%AE%8C%E6%95%B4%E6%A8%A1%E5%9D%97%E5%92%8C%E4%BE%9D%E8%B5%96%E5%BA%93%EF%BC%8C%E9%80%82%E7%94%A8%E4%BA%8E%E5%A4%A7%E5%A4%9A%E6%95%B0%E9%83%A8%E7%BD%B2%E5%9C%BA%E6%99%AF%E3%80%82

freeradius/freeradius-server:<version>-alpine

轻量级镜像，基于https://hub.docker.com/_/alpine/%EF%BC%8C%E4%BD%93%E7%A7%AF%E6%98%BE%E8%91%97%E5%B0%8F%E4%BA%8EUbuntu%E7%89%88%E6%9C%AC%E3%80%82**%E6%B3%A8%E6%84%8F**%EF%BC%9A%E4%B8%BA%E6%9C%80%E5%B0%8F%E5%8C%96%E9%95%9C%E5%83%8F%E4%BD%93%E7%A7%AF%EF%BC%8C%E6%AD%A4%E5%8F%98%E4%BD%93%E4%B8%8D%E5%8C%85%E5%90%AB%E6%89%80%E6%9C%89%E6%A8%A1%E5%9D%97%E7%9A%84%E4%BE%9D%E8%B5%96%E5%BA%93%EF%BC%88%E5%B0%A4%E5%85%B6%E6%98%AFPerl%E3%80%81Python%E7%AD%89%E8%AF%AD%E8%A8%80%E6%A8%A1%E5%9D%97%EF%BC%89%EF%BC%8C%E5%A6%82%E9%9C%80%E4%BD%BF%E7%94%A8%E8%BF%99%E4%BA%9B%E5%8A%9F%E8%83%BD%EF%BC%8C%E9%9C%80%E5%9C%A8%E8%87%AA%E5%AE%9A%E4%B9%89Dockerfile%E4%B8%AD%E9%80%9A%E8%BF%87%60apk add`安装相应依赖。

构建Docker镜像

源码中的Dockerfile

FreeRADIUS源码仓库包含多种Linux发行版的Dockerfile模板，位于https://github.com/FreeRADIUS/freeradius-server/tree/v3.0.x/scripts/docker%EF%BC%88%E5%B0%86%60<os_name>`替换为具体发行版名称）。

基础构建命令

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

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

bash
$ 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提交哈希或标签（指定构建版本）

示例：从特定版本构建

console
$ docker build . \
  --build-arg=release=v3.0.x \
  --build-arg=source=https://github.com/FreeRADIUS/freeradius-server.git \
  -t freeradius-custom