平台功能与 VPS 线上部署安装说明

日期：2026-03-22

1. 文档目的

本文档基于当前仓库的实际实现，说明两件事：

  1. 当前平台已经具备哪些可用功能
  2. 如何把当前版本部署到 VPS 线上运行

本文档不按理想架构写，而按当前已经能落地的能力写，重点是可交付、可上线、可验证。

2. 平台当前功能总览

当前平台不是单一的 TR069 工具，也不是单一的 VPN 管理器，而是一套面向公寓宽带场景的管理、计费、设备纳管、运维一体化平台。

2.1 计费与认证能力

当前后端已经具备完整的 RADIUS 基础能力：

  • Access-Request 认证
  • Accounting-Start / Interim-Update / Acct-Stop 记账
  • 在线会话记录与离线日志归档
  • 流量、时长、配额扣减
  • 配额耗尽时断线
  • RADIUS 调试日志与数据库核验工具

这部分能力决定“用户能不能上网、用了多少、是否超额、是否该断”。

2.2 NAS / iKuai 管理能力

当前平台已经具备 NAS 设备管理能力，重点围绕 iKuai 使用：

  • NAS 设备信息管理
  • iKuai API 配置管理
  • PPP 在线会话查询
  • PPP 指定会话踢线
  • 按 VPN 账号绑定的 LAN 网段做 iKuai Web 代理访问
  • 区域维度的 NAS 与 VPN 账号统计

这部分能力决定“怎么运维现场网关和宽带接入设备”。

2.3 VPN 账号与远程接入能力

当前平台仍然保留完整的 VPN 业务能力，主要包括：

  • VPN 账号管理
  • 批量生成 VPN 账号
  • VPN 账号绑定 NAS
  • VPN 建链后的 ip-up 回调标记账号已使用
  • 返回对应 LAN 网段，配合脚本加路由
  • 作为 iKuai 内网代理访问的安全边界

结论要说清楚：

  • 对现在的 TR069 直改 ACS 方案，VPN 不再是必需前提
  • 但对 NAS / iKuai 远程管理、账号分配、内网代理访问来说，VPN 仍然有实际用途

2.4 TR069 光猫纳管与 MiniACS 能力

当前 TR069 模块已经不是早期演示状态，已经具备可实际使用的纳管和下发能力：

  • 公开 CWMP 入口
  • MiniACS 会话处理
  • Inform 入库
  • 设备列表、详情、事件、参数快照展示
  • 模板任务下发
  • 改 WiFi、重启、下载、参数读取
  • 手动触发 Connection Request
  • 自动状态评估（在线 / 离线）
  • 设备绑定宽带账号后自动编排业务模板

2.5 多品牌兼容能力

本轮强化后，TR069 模块已经具备以下兼容增强：

  • 区分 TR-098 与 TR-181 根模型
  • 参数路径映射与运行时重写
  • 能力探测与兼容指纹
  • 写后校验与回读诊断
  • 兼容状态、探测状态、映射诊断展示

这意味着当前平台已经不只是“能接设备”，而是开始具备“多品牌可运营”的基础。

2.6 当前推荐接入方式

如果现场可以直接修改光猫 ACS 地址，当前推荐方式是：

  • 直接把光猫 ACS URL 改到平台公开入口
  • 平台通过 MiniACS 接收 Inform 和下发任务
  • 不再把 VPN 作为 TR069 主链路的前置条件

如果现场不能改光猫、仍然需要接管原 ACS 链路，才继续使用：

  • VLAN46 + iKuai 导流
  • DNS/端口劫持
  • 可选 VPN 把链路固定到 VPS

3. VPN 在当前体系中的定位

这一点容易混淆，单独说明。

3.1 对 TR069 来说

在“直接修改 ACS”模式下：

  • VPN 不是必需
  • 光猫只要能访问平台公开 ACS 地址即可

3.2 对 NAS 来说

在当前实现中：

  • VPN 仍然有用
  • 它承担 NAS/iKuai 内网接入、代理访问、账号绑定、路由回传等职责

3.3 当前建议

当前最合理的策略不是删除 VPN，而是调整角色：

  • TR069 主流程：以直改 ACS 为主
  • NAS 内网管理：继续保留 VPN 能力
  • 劫持接管：仅作为无法改 ACS 时的备用方案

4. 线上部署目标架构

当前推荐的 VPS 部署形态如下：

公网用户/设备
    |
    v
Nginx(80/443，可选 9090/7547)
    |
    +--> Vue 前端静态文件
    |
    +--> GoFrame 后端 :8100
             |
             +--> MySQL
             +--> Redis
             +--> MiniACS / RADIUS / NAS / VPN 业务

建议遵循以下端口角色：

  • 80/443：平台前端和 API 统一入口
  • 8100：Go 后端本地监听端口
  • 9090 或 7547：TR069 对外入口，可由 Nginx 转发到 8100
  • 6379：Redis
  • 3306：MySQL
  • 1812/1813：RADIUS，如需对外提供认证计费则需放行 UDP

5. VPS 部署前准备

上线前至少确认以下前提：

5.1 服务器环境

  • Linux VPS
  • 已安装 Nginx
  • 已安装 Redis，或可访问独立 Redis
  • 可访问 MySQL 数据库
  • 具备 systemd 或 supervisor 进程托管能力

5.2 构建环境

后端构建命令：

cd gf-server
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o billingChuanghui main.go

前端构建命令：

cd vue-admin
npm install
npm run build

5.3 运行依赖

后端依赖以下目录和文件：

  • gf-server/billingChuanghui
  • gf-server/manifest/config/config.yaml
  • gf-server/resource/
  • gf-server/scripts/

如果仍需保留劫持方案，还需要：

  • gf-server/scripts/install_tr069_hijack.sh

6. 推荐部署目录结构

推荐在 VPS 上使用如下结构：

/opt/billing/
  gf-server/
    billingChuanghui
    manifest/
      config/
        config.yaml
    resource/
    scripts/
  vue-admin/
    dist/

要求：

  • resource/log 目录必须可写
  • config.yaml 必须与实际数据库、Redis、域名保持一致
  • scripts 目录必须保留，避免后台远程部署、自检、历史脚本找不到

7. 关键配置项说明

上线时重点检查以下配置。

7.1 后端监听

当前默认监听：

server:
  address: ":8100"

建议保持不变，由 Nginx 做公网转发。

7.2 Redis

当前缓存模型为 Redis，MiniACS 会话依赖 Redis：

system:
  cache:
    model: "redis"

7.3 TR069 设备应写入的 ACS 地址

当前配置支持固定设备应连接的 ACS URL：

tr069:
  deviceAcsUrl: "http://你的公网IP或域名:9090/api/v1/tr069/cwmp"

这项非常关键。

  • 如果现场是直接改 ACS，这里应配置成公网可达地址
  • 不要误写成 127.0.0.1 或内网地址

7.4 VPN 回调

如果要保留 VPN 账号回调链路，需要确认：

vpn:
  l2tp:
    notifyUrl: "https://你的域名/api/v1/system/sysPptp/markUsed"
    notifyToken: "你的token"

8. 线上安装步骤

第 1 步：构建发布产物

在本地执行：

cd /Applications/chuanghui/billing/gf-server
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o billingChuanghui main.go

cd /Applications/chuanghui/billing/vue-admin
npm install
npm run build

第 2 步：上传文件到 VPS

上传以下内容：

  • gf-server/billingChuanghui
  • gf-server/manifest/config/config.yaml
  • gf-server/resource/
  • gf-server/scripts/
  • vue-admin/dist/

第 3 步：在 VPS 上准备目录

mkdir -p /opt/billing/gf-server
mkdir -p /opt/billing/vue-admin
mkdir -p /opt/billing/gf-server/resource/log/run
mkdir -p /opt/billing/gf-server/resource/log/sql

第 4 步：部署后端文件

将后端文件放到：

  • /opt/billing/gf-server/billingChuanghui
  • /opt/billing/gf-server/manifest/config/config.yaml
  • /opt/billing/gf-server/resource/
  • /opt/billing/gf-server/scripts/

然后赋权：

cd /opt/billing/gf-server
chmod +x billingChuanghui
find scripts -type f -name "*.sh" -exec chmod +x {} \;

第 5 步：部署前端文件

将 vue-admin/dist 上传到：

  • /www/wwwroot/billing.chuanghui100.com/sys/

或你自己的静态站点目录。

第 6 步：配置 Nginx

建议至少配置三类入口：

  1. 前端静态页面 /sys/
  2. 后端 API /api/
  3. TR069 入口 9090 或 7547

最小反代示例：

server {
    listen 80;
    server_name your-domain.com;

    root /www/wwwroot/billing.chuanghui100.com;
    index index.html;

    location /api/ {
        proxy_pass http://127.0.0.1:8100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /sys/ {
        try_files $uri $uri/ /sys/index.html;
    }
}

如果设备要求使用 9090 或 7547，可增加单独 server：

server {
    listen 9090;
    server_name _;

    location / {
        proxy_pass http://127.0.0.1:8100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

第 7 步：启动后端程序

先手工启动，确认无报错：

cd /opt/billing/gf-server
./billingChuanghui

如果日志正常，再改成 systemd 托管。

第 8 步：配置 systemd

示例：

[Unit]
Description=Billing Platform
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/billing/gf-server
ExecStart=/opt/billing/gf-server/billingChuanghui
Restart=always
RestartSec=5
User=root

[Install]
WantedBy=multi-user.target

执行：

sudo systemctl daemon-reload
sudo systemctl enable billing
sudo systemctl start billing
sudo systemctl status billing

9. 上线后验证顺序

建议严格按顺序验证，不要一上来就抓包。

9.1 基础存活检查

检查：

  • 前端页面是否可访问
  • /api/ 是否反代正常
  • 后端日志是否持续输出
  • Redis 和 MySQL 是否连接成功

9.2 平台功能检查

后台登录后至少确认：

  • NAS 设备列表可打开
  • VPN 列表可打开
  • TR069 设备列表可打开
  • 模板与任务管理页可打开

9.3 TR069 检查

如果走直接改 ACS 模式，确认：

  • 光猫 ACS URL 已改为平台公网地址
  • 设备能触发 Inform
  • 设备进入 TR069 清单
  • 最近 Inform 时间刷新
  • 可成功下发至少一个任务

9.4 NAS / VPN 检查

如果保留 NAS + VPN 体系，确认：

  • VPN 账号可创建
  • ip-up 回调能打到 sysPptp/markUsed
  • PPP 在线查询可返回结果
  • PPP 踢线可执行
  • iKuai 代理访问受 LAN 网段限制且可用

9.5 RADIUS 检查

如果线上同时启用计费认证，确认：

  • UDP 1812/1813 已监听
  • NAS 能正常发起 RADIUS 请求
  • 在线会话可入库
  • Interim 和 Stop 正常累积与归档

10. 当前推荐的上线策略

基于当前功能状态，推荐这样使用平台：

10.1 主线能力

  • 计费与认证：继续作为平台底座
  • NAS / iKuai：继续保留
  • VPN：继续作为 NAS 内网接入和代理访问能力保留
  • TR069：以直改 ACS 为主线方案

10.2 备用能力

  • 劫持接管：仅在不能修改光猫 ACS 时使用
  • VPN 强制 TR069 走隧道：仅在现场网络受限时使用

10.3 当前不建议的做法

  • 不建议把 VPN 从平台中整体删除
  • 不建议继续把 VPN 视为 TR069 直连方案的必要前提
  • 不建议上线时同时大改端口、目录、缓存模型和 ACS 地址规则

11. 最终结论

当前平台已经具备以下可上线基础：

  • RADIUS 计费认证
  • NAS / iKuai 运维管理
  • VPN 账号与远程接入
  • TR069 设备纳管与任务下发
  • 多品牌兼容增强与状态诊断

从部署角度看，当前版本已经适合部署到 VPS 做线上运行。

从网络角色看：

  • TR069 直改 ACS 模式下，VPN 不是必需
  • NAS / iKuai 管理场景下，VPN 仍然有实际用途

因此当前最合理的上线定位是：

  • 以 VPS 为统一平台入口
  • 以前端 + Go 后端 + Redis + MySQL 的标准方式部署
  • 以直改 ACS 为 TR069 主链路
  • 保留 VPN 作为 NAS 管理和内网代理访问能力
作者：wuge  创建时间：2026-01-31 16:30
最后编辑：wuge  更新时间：2026-03-23 11:08