SafeLine 配置参数详解

目标：逐参数讲清 SafeLine（雷池）社区版 9.4.2 的两类配置——Compose 环境变量与防护站点配置，每项给出修改方法与实测验证结论；核心参数均按「改值 → 重启 → 行为对比」方式实测。

一、环境信息

• SafeLine 版本：SafeLine CE 9.4.2（社区版）
• 部署形态：官方 Compose 模板，7 服务（mgt / detector / tengine / pg / fvm / luigi / chaos）
• 数据目录：/opt/data/safeline（SAFELINE_DIR）
• 管理端口：13905（MGT_PORT，服务内固定 1443，HTTPS）
• 站点检测端口：13907；后端源站：13990（nginx 1.27 静态站）
• 实测方式：修改 .env 后 docker compose up -d 重建服务对比行为；防护站点配置通过控制台同源的管理接口读写后用 curl 验证
• 系列文档：《SafeLine Docker Compose 部署指南》《SafeLine 介绍与选型指南》《SafeLine 运维手册》

二、参数总览与修改方式

SafeLine 的配置分三层，修改方式与生效路径不同：

修改 .env 后的标准操作：

root@waf01:/opt/data/safeline# vim .env
root@waf01:/opt/data/safeline# docker compose up -d

注意：docker compose restart 不会重读 .env（restart 只是重启进程），必须用 up -d 让 Compose 按新变量重建服务。

三、Compose 环境变量逐项实测

.env 完整变量与官方 docker-compose.yaml 的引用关系（模板实测核对）：

3.1 MGT_PORT（管理端口）——实测改值

将 13905 改为 13908 并重建：

root@waf01:/opt/data/safeline# sed -i 's/^MGT_PORT=13905$/MGT_PORT=13908/' .env && grep MGT_PORT .env
MGT_PORT=13908
root@waf01:/opt/data/safeline# docker compose up -d
 Container safeline-mgt Recreate
 Container safeline-mgt Recreated
 Container safeline-mgt Starting
 Container safeline-mgt Started

行为对比（改后 curl 实测）：

root@waf01:/opt/data/safeline# curl -sk -o /dev/null -w 'port 13908: %{http_code}\n' https://127.0.0.1:13908/
port 13908: 200
root@waf01:/opt/data/safeline# curl -sk -o /dev/null -w 'port 13905: %{http_code}\n' --max-time 3 https://127.0.0.1:13905/ ; echo "exit=$?"
port 13905: 000
exit=28

结论：新端口 200、旧端口连接失败（000/超时），管理端口改值立即生效；业务站点端口（13907）不受影响。实测后已改回 13905。改端口后登录浏览器地址需同步更新，一次性密码 reset-admin 命令与端口无关。

3.2 SUBNET_PREFIX（内部网段前缀）

静态 IP 编排（模板指定）：pg=.2、mgt=.4、detector=.5、fvm=.8、chaos=.10；网关通过固定 IP 对接内部组件：

- TCD_MGT_API=https://${SUBNET_PREFIX}.4:1443/api/open/publish/server
- TCD_SNSERVER=${SUBNET_PREFIX}.5:8000
- CHAOS_ADDR=${SUBNET_PREFIX}.10

实测结论：本次部署因宿主已占用 172.22.0.0/16，改为 SUBNET_PREFIX=172.16.222，全套服务正常启动且建站/检测/日志链路完整。注意该变量改动必须整套重建（网络与静态 IP 全部重建），且与宿主其他网络网段冲突时会创建失败（pool overlaps）。

3.3 POSTGRES_PASSWORD（数据库密码）

被 mgt / luigi / chaos 的数据库连接串引用（实测模板片段）：

- MGT_PG=postgres://safeline-ce:${POSTGRES_PASSWORD}@safeline-pg/safeline-ce?sslmode=disable
- LUIGI_PG=postgres://safeline-ce:${POSTGRES_PASSWORD}@safeline-pg/safeline-ce?sslmode=disable
- DB_ADDR=postgres://safeline-ce:${POSTGRES_PASSWORD}@safeline-pg/safeline-ce?sslmode=disable

行为要点：密码在数据库目录首次初始化（initdb）时固化；首次启动后修改 .env 中的该变量不会改变数据库实际密码，只会导致各服务连接失败。改库密码的正确姿势是进库执行 ALTER USER 后同步 .env。实测库：docker exec safeline-pg psql -U safeline-ce -d safeline-ce 可直接登录（本机免密），密码主要用于外部工具连库。

3.4 IMAGE_TAG / IMAGE_PREFIX / ARCH_SUFFIX / POSTGRES_IMAGE

镜像名合成规则（模板原文）：

image: ${IMAGE_PREFIX}/safeline-mgt${REGION}${ARCH_SUFFIX}:${IMAGE_TAG:?image tag required}   # mgt
image: ${POSTGRES_IMAGE:-${IMAGE_PREFIX}/safeline-postgres${ARCH_SUFFIX}:15.18}               # pg

• IMAGE_TAG：业务镜像版本。latest 跟随最新；锁定版本填官方 Release 号（如 9.4.2 对应镜像 tag）
• IMAGE_PREFIX：换私有仓库时改（离线部署：导入镜像后改前缀）
• ARCH_SUFFIX：x86_64 留空；ARM 服务器填 -arm64
• POSTGRES_IMAGE：数据库镜像整体覆盖，默认锁定 15.18 版本，不受 IMAGE_TAG 影响
• 实测镜像清单（docker images 回显）：mgt 124MB、detector 403MB、tengine 202MB、postgres 809MB、fvm 445MB、luigi 261MB、chaos 368MB

3.5 MGT_PROXY / REGION / RELEASE

• MGT_PROXY：mgt 出网代理（规则库更新、License 校验等走代理）。留空启动会打印一条 warning（The "MGT_PROXY" variable is not set，实测回显），不影响功能；隔离环境需要规则更新时填 http://host:port
• REGION：拼在镜像名中的区域变体位，国内 x86_64 留空
• RELEASE：现行 compose 模板未引用（模板全量 grep 核对），官方 setup.sh 写入的兼容字段，留空

四、防护站点配置逐参数实测

4.1 站点配置结构（实测读取回显）

新建站点后的完整配置（管理接口读取，节选）：

root@waf01:~# curl -sk https://127.0.0.1:13905/api/open/site/1 -H "Authorization: Bearer <JWT>" | python3 -m json.tool
{
    "data": {
        "id": 1,
        "server_names": [
            "safeline-demo.local"
        ],
        "ports": [
            "13907"
        ],
        "upstreams": [
            "http://192.168.146.128:13990"
        ],
        "is_enabled": true,
        "mode": 2,
        "load_balance": {
            "balance_type": 1,
            "upstreams": [
                {
                    "address": "http://192.168.146.128:13990",
                    "weight": 1,
                    "role": "primary"
                }
            ]
        },
        ...（其余为证书/防护开关/动态防护等默认项）
    },
    "err": null
}

4.2 站点基础参数

4.3 站点端口行为实测

root@waf01:~# ss -tlnp | grep 13907
LISTEN 0      511          0.0.0.0:13907      0.0.0.0:*   users:(("nginx",...))

站点保存后网关（tengine，host 网络）立即在宿主监听 13907，进程即网关自身的 nginx。正常请求与拦截行为：

root@waf01:~# curl -s -o /dev/null -w 'normal: %{http_code}\n' -H 'Host: safeline-demo.local' http://127.0.0.1:13907/
normal: 200
root@waf01:~# curl -s -o /dev/null -w 'attack: %{http_code}\n' -H 'Host: safeline-demo.local' 'http://127.0.0.1:13907/?id=1%20union%20select%201,2,3'
attack: 403

4.4 排错路径（误拦截加白）实测

站点配置中的 exclude_paths（URL 前缀/Content-Type 排除）用于业务被误拦截时放行指定路径。实测写入：

root@waf01:~# curl -sk -X POST https://127.0.0.1:13905/api/open/site/1/excludes \
  -H "Authorization: Bearer <JWT>" -H 'Content-Type: application/json' \
  -d '{"prefixes":["/report"],"content_types":[]}'
{"data":{"prefixes":["/report"],"content_types":[]},"err":null,"msg":""}

配置已入库（重新读取站点配置可见 exclude_paths 同步为该值）。实测注意：v9.4.2 中通过接口写入排除后，误拦样本（/report?expr=1 or 1=1 -- test）在重启 mgt 及网关后仍返回 403，未即时放行；该功能以控制台「网站管理 → 站点详情 → 排错路径」操作为准，接口侧行为（是否需要附加动作字段/配置版本推送）存在差异。运维排错时若加白未生效，优先在控制台操作并等待配置下发（见《SafeLine 运维手册》误拦截处理章节）。

4.5 站点配置下发机制

站点配置存数据库，管理服务（mgt）负责把配置渲染成网关配置并推送到 tengine（站点文件名形如 IF_backend_1，路径 /etc/nginx/sites-enabled/）。实测网关侧配置关键行（节选）：

root@waf01:~# docker exec safeline-tengine sh -c 'grep -nE "listen|proxy_pass|server |upstream|backend_1" /etc/nginx/sites-enabled/IF_backend_1'
4:upstream backend_1 {
5:    server 192.168.146.128:13990;
12:server {
13:    listen 0.0.0.0:13907;
27:        proxy_pass http://unix:/app/sock/tcd_error.sock;    （拦截/错误页，本地套接字）
63:        proxy_pass http://172.16.222.10:8080/challenge/v2/; （人机验证挑战页）
74:        proxy_pass http://backend_1;                        （放行流量转发源站）
78:        include /etc/nginx/custom_params/backend_1;

含义：站点层的参数（端口、域名、上游、负载）最终都落到该配置文件——listen 0.0.0.0:13907 即 ports 参数、upstream backend_1 即上游与负载配置；错误页走本地 tcd_error.sock 套接字（内嵌 T1K 检测插件交互），挑战页转发 chaos（.10:8080），放行流量 proxy_pass 到源站。因此改站点参数不需要重启网关，保存即由管理服务重新渲染下发；若配置下发异常（网关 404/域名不匹配），可执行 docker exec safeline-mgt /app/mgt-cli gen-tengine-website（regen full website for tengine，实测帮助原文）或官方 reset_tengine.sh 重建网关配置。

五、组件内部参数（排查用）

模板注入各服务的内部环境变量（排障时进入对应服务核对）：

六、常见问题（FAQ）

6.1 改了 .env 不生效

原因：用 docker compose restart 只重启进程不重读变量。处理：docker compose up -d 重建（输出中看到 Recreate/Recreated 才是重建生效，实测回显见 3.1）。

6.2 修改 POSTGRES_PASSWORD 后全套服务起不来

原因：首次初始化后数据库密码已固化，仅改 .env 会导致连接串错。处理：还原 .env 原值；确需改密码时先在库内 ALTER USER 再同步 .env。

6.3 站点保存后访问仍 404/域名不匹配

原因：请求 Host 与 server_names 不匹配，或配置下发异常。处理：核对域名与端口；网关侧核对 /etc/nginx/sites-enabled/IF_backend_N 是否生成；异常时执行官方 reset_tengine.sh 重建网关配置。

6.4 管理端口改了浏览器打不开

原因：端口改值后旧地址失效（实测旧端口 000）。处理：用新端口访问；防火墙/安全组同步放行新端口。

6.5 想锁定版本不跟随 latest

处理：.env 中 IMAGE_TAG 填固定版本标签，IMAGE_PREFIX 指向私有仓库；升级操作与风险见《SafeLine 运维手册》。

七、参数修改速查表

八、参考链接

• GitHub 仓库与版本发布（9.4.2 版本核实）：https://github.com/chaitin/SafeLine/releases
• 官方文档站（站点配置参考）：https://docs.waf.chaitin.cn/
• 系列文档：《SafeLine Docker Compose 部署指南》《SafeLine 运维手册》《SafeLine 介绍与选型指南》