FreeRADIUS Docker镜像文档

1. 镜像概述

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

FreeRADIUS广泛应用于大规模网络环境，支持每日为数亿用户提供互联网访问认证服务，适用场景从10用户的小型网络到1000万+用户的大型部署。

2. 核心功能与特性

• 多协议支持：原生支持RADIUS、DHCPv4和VMPS协议，满足多样化网络策略需求。
• 高性能与可扩展性：优化的处理引擎，支持从几十到千万级用户规模的平滑扩展。
• 丰富认证场景：兼容802.1x（WiFi）、拨号网络、PPPoE、***、VoIP等多种接入方式的认证需求。
• 多后端数据库集成：支持MySQL、PostgreSQL、Oracle、Microsoft Active Directory、Redis、OpenLDAP等后端数据存储。
• 高度可配置：通过模块化设计和灵活的策略规则，适应不同网络环境的定制需求。

3. 使用场景与适用范围

适用场景

• 企业WiFi（802.1x）网络接入认证
• ***远程访问用户身份验证
• ISP宽带用户PPPoE接入管理
• VoIP服务用户认证与授权
• 大型园区网络集中化访问控制

适用范围

• 需要集中管理网络访问权限的企业或组织
• 提供网络接入服务的ISP和运营商
• 部署VoIP、***等服务的通信服务商
• 从小型办公网络到大型数据中心的各类网络环境

4. 使用方法与配置说明

4.1 启动默认容器

默认镜像仅包含基础配置（无用户、仅允许127.0.0.1客户端访问），需自定义配置后才能实际使用：

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

注意：默认配置下容器不会响应任何请求，必须自定义配置后才能用于生产环境。

4.2 自定义配置

4.2.1 创建本地配置文件

需创建包含客户端和用户信息的配置文件，典型目录结构如下：

raddb/
├── clients.conf        # 客户端配置
└── mods-config/
    └── files/
        └── authorize   # 用户认证信息

clients.conf（定义允许访问的客户端）：

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

authorize（定义测试用户）：

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

4.2.2 构建自定义镜像

创建Dockerfile整合配置：

Dockerfile
FROM freeradius/freeradius-server:latest
COPY raddb/ /etc/raddb/  # 将本地配置复制到容器

构建镜像：

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

4.3 运行自定义配置容器

启动容器并映射RADIUS默认端口（1812/udp认证，1813/udp记账）：

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

4.3.1 测试认证

使用radtest工具测试（需安装FreeRADIUS客户端工具）：

bash
radtest bob test 127.0.0.1 0 testing123

成功时返回"Access-Accept"。停止容器：

bash
docker stop my-radius

4.4 调试模式运行

使用-X参数启动调试模式（需添加-t参数支持彩色输出）：

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

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

4.5 安全注意事项

• 默认镜像包含自签名证书，仅用于测试，生产环境必须替换为可信证书（详见容器内/etc/raddb/certs/README.md）。
• 客户端共享密钥（secret）需使用高强度随机字符串，避免硬编码在配置文件中。
• 限制客户端IP段，避免开放过宽的访问范围。

4.6 调试技巧

使用gdb调试容器内进程时，需添加--privileged参数以获取必要权限：

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

5. 镜像变体

5.1 freeradius/freeradius-server:<version>

默认镜像，基于Ubuntu Linux构建，包含完整依赖，推荐生产环境使用。

5.2 freeradius/freeradius-server:<version>-alpine

基于Alpine Linux的轻量级镜像，体积更小，但不包含所有模块依赖（尤其是Perl、Python等语言相关库）。如需使用依赖这些库的模块，需在自定义Dockerfile中通过apk add安装相应依赖。

6. 构建Docker镜像

6.1 源码构建环境

FreeRADIUS源码中包含多平台Dockerfile，路径：
freeradius-server/scripts/docker/<os_name>

6.2 基本构建步骤

bash
cd scripts/docker/<os_name>  # 如ubuntu、alpine等
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

6.3 构建参数

Dockerfile支持以下构建参数：

• source：源码仓库URL（默认：FreeRADIUS***仓库）
• release：Git提交/tag（默认：最新稳定版）

示例：构建指定版本和仓库的镜像

bash
docker build . \
  --build-arg=release=v3.0.x \
  --build-arg=source=[***] \
  -t freeradius-<os_name>