部署与节点接入¶
本文说明服务组件、端口与接入流程。生产使用前应为控制面配置备份、监控和访问控制；管理域名必须启用 HTTPS。
组件¶
- 控制 API：Go 服务，提供管理 API、首次管理员初始化、节点注册和配置同步。
- PostgreSQL：保存用户、节点、规则、配额、用量、审计记录和节点证书状态。
- Web 管理台：静态前端，由 Nginx 与控制 API 同域反向代理。
- 文档站：静态站点，可由 Nginx 直接托管。
- 转发节点：独立运行
relay-agent；入口节点接受转发流量，出口节点按授权规则连接目标。
网络端口¶
在系统防火墙和云防火墙中只开放实际使用的端口：
| 用途 | 协议 | 默认值 | 说明 |
|---|---|---|---|
| 管理台与文档 | TCP | 80、443 | 80 用于 HTTPS 跳转及 ACME；管理台与 API 使用 443 |
| 节点注册 | TCP | 9443 | 节点首次接入和证书轮换，TLS |
| 节点控制会话 | TCP | 9444 | 节点 mTLS 控制通道 |
| 节点间数据面 | UDP | 8444 | 出口 QUIC 数据面；每台出口应使用独立可达地址/端口 |
| 转发规则监听 | 按规则配置 | 自选 | 入口 TCP/UDP 端口，须与规则及防火墙匹配 |
控制面地址、节点控制地址和数据面地址是不同用途。节点的 data_plane_address 必须是入口节点可达的出口 QUIC 地址；DNS、NAT 与防火墙需允许对应 UDP 流量。
构建¶
在本地完整源码目录执行：
make build-api build-agent build-web build-docs
需要 Go 1.26 或更新版本、Node.js 22 或更新版本，以及 uv。首次文档构建会按 docs-site/requirements.txt 在隔离缓存中安装 MkDocs Material。生产服务器只需运行 Go 二进制并托管静态文件，不需要 Go、Node.js 或 MkDocs 工具链。
控制面配置¶
从 .env.example 建立仅服务账户可读的环境文件，替换数据库连接、TLS 证书路径与一次性管理员初始化值。应用只从进程环境读取配置，不解析 dotenv 文件。TLS 节点服务器证书必须由 NODE_CA_CERT_FILE 指定的 CA 签发并包含控制面主机名；CA 私钥与节点服务器私钥必须限制为服务账户可读。不要把私钥放入源码、Web 根目录或普通备份包。
首次启动前建立数据库与专用低权限数据库用户。服务启动时会按版本应用 SQL 迁移。启动后访问管理域名，通过初始化令牌创建首个管理员；随后从服务环境中移除 BOOTSTRAP_ADMIN_TOKEN 并重启服务。管理员账号密码应使用密码管理器保存。
将控制 API 绑定到回环地址，由 Nginx 代理 /api/ 与 /healthz。不要把未加密的控制 API 直接开放到公网。管理台静态构建位于 web/dist；文档站静态构建位于 docs-site/site。
发布包包含 bin/、web/、docs/、环境模板和源码提交标识。将 web/ 与 docs/ 分别部署到 /opt/traffic-forwarding/web、/opt/traffic-forwarding/docs，二进制部署到 /opt/traffic-forwarding/bin/。仓库的 deploy/systemd/ 提供服务单元示例；deploy/nginx/ 提供管理台与文档站配置示例。若使用宝塔，请先在面板中为两个域名分别配置 HTTPS 证书，再按样例配置静态目录和 API 反向代理。样例中的证书路径仅作示例，应替换为宝塔实际证书路径。
控制面环境文件示例位于 .env.example。复制为 /etc/traffic-forwarding/control-api.env，设置 0600 权限并由 traffic-forwarding 服务账户读取。安装 control-api.service 后启用服务。数据库应使用独立账户；数据库 URL 与临时 bootstrap token 不得放入 Nginx 配置、Web 静态目录或发布包。
创建节点控制 CA 与服务端证书¶
管理台的 HTTPS 证书与节点 gRPC 控制通道证书用途不同。下面示例创建私有节点 CA，并签发 SAN 包含 testmb.o39.cn 的节点控制服务端证书；若节点使用其他域名连接，应把实际 DNS 名称加入 SAN。CA 私钥只保存在受限的控制面密钥目录，节点仅复制 node-ca.crt。
umask 077
install -d -m 0700 /etc/traffic-forwarding/pki
cd /etc/traffic-forwarding/pki
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out node-ca.key
openssl req -x509 -new -key node-ca.key -sha256 -days 3650 \
-subj "/CN=Traffic Forwarding Node CA" \
-addext "basicConstraints=critical,CA:TRUE" \
-addext "keyUsage=critical,keyCertSign,cRLSign" -out node-ca.crt
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out node-server.key
openssl req -new -key node-server.key -subj "/CN=testmb.o39.cn" -out node-server.csr
cat > node-server.ext <<'EOF'
basicConstraints=critical,CA:FALSE
subjectAltName=DNS:testmb.o39.cn
extendedKeyUsage=serverAuth
keyUsage=digitalSignature,keyEncipherment
EOF
openssl x509 -req -in node-server.csr -CA node-ca.crt -CAkey node-ca.key \
-CAcreateserial -out node-server.crt -days 365 -sha256 -extfile node-server.ext
chmod 0600 node-ca.key node-server.key
把 CA 证书、服务端证书和私钥路径配置到 .env.example 对应项。不要将 CA 私钥复制到节点或发布包；节点证书由控制面通过 CSR 按节点签发。
节点接入¶
- 在管理台创建入口或出口节点组，并创建待接入节点，填写唯一节点名、控制地址与可达的数据面地址。
- 为该节点签发一次性接入令牌。令牌只显示一次，请通过受控渠道传给节点管理员并及时删除临时记录。
- 在节点安装
relay-agent，将控制面服务器 CA 证书放到只读位置；为每个节点使用独立数据目录和专用服务账户。 - 设置节点环境：
sh
CONTROL_ENROLL_ADDR=testmb.o39.cn:9443
CONTROL_SESSION_ADDR=testmb.o39.cn:9444
CONTROL_SERVER_CA_FILE=/etc/traffic-forwarding/node-ca.crt
NODE_ENROLLMENT_TOKEN=一次性令牌
RELAY_NODE_NAME=与管理台登记名称完全一致
RELAY_AGENT_DATA_DIR=/var/lib/traffic-forwarding
RELAY_DATA_LISTEN_ADDR=0.0.0.0:8444
NODE_HEARTBEAT_INTERVAL=20s
RELAY_DATA_LISTEN_ADDR 主要用于出口节点；入口节点使用控制面分配的规则监听端口。
- 以 systemd 运行节点服务。环境文件权限设为
0600；接入成功后删除NODE_ENROLLMENT_TOKEN，保留节点数据目录中的私钥、证书、配置与用量队列。 - 确认节点在线且配置版本已应用，再创建转发规则。创建规则前，先在用户组配置允许的目标网段和端口；规则目标的 DNS 所有地址必须都在同一用户组授权范围内。
节点数据目录包含设备身份、节点私钥、最后可用规则快照、配额租约与待上报用量队列。不得删除、复制到另一台节点或公开该目录。遗失后应停用旧节点并重新注册；未确认的租约会保守保留，避免重复分配额度。
服务运行检查¶
GET /healthz返回200表示 API 能连接数据库。- 管理台节点页显示在线、心跳时间与目标配置版本一致。
- 检查 systemd 日志中的启动错误、TLS 证书有效期、数据库连接和节点同步状态。
- 后台备份 PostgreSQL 与受限的 TLS/CA 材料；独立备份并保护每个节点的数据目录。恢复时确保同一节点身份不会在两台机器上同时运行。
本项目不包含支付、商城或自动邮件发送。接入令牌由管理员在界面中手动交付。