# 05. 分阶段实现计划

> **维度**：B · 产品实现（Impl-Phase）
> 本文档的"阶段"全部指 **Impl-Phase**（功能交付顺序），与 playbook 的 Biz-Stage（商业路线图）是正交关系。
> 实际进度以 `stage-1-readiness.md`（维度 D · 就绪度快照）为准。

## 阶段 1：先把入口和骨架立起来

目标：

- 官网可访问
- 登录页可访问
- 注册页可访问
- `/admin` 骨架可访问
- `/portal` 骨架可访问
- 文档拆分落地

这个阶段先解决"产品像一个完整系统"，而不是继续停留在散落页面。

### 阶段 1 代码动作

- 新增 Web 入口模块
- 给 NestJS 增加静态页面路由
- 落官网、登录、注册、后台、门户 5 个入口页面
- 保留 `/ops`

### 阶段 1 出口节点 MVP（Egress MVP）

在阶段 1 同期完成出口节点最小可用部署，让自用验证能跑通：

- 修复 `serverBaseUrl` 硬编码（从环境变量读取）
- 修复 `bumpDesiredConfigVersion` 接入 publish 流程（映射变更触发配置下发）
- 修复 `auth_token` 注册时自动生成（避免 frps 安全裸奔）
- 增强 `buildInstallScript`：下载二进制 + systemd service + 配置目录
- 明确出口仅承载 TCP/UDP 端口映射，Web 暴露面由用户自理
- 明确出口不再配置 `TCP/UDP` 支持协议，协议仅在映射层选择
- 安装脚本自动开放 OS 防火墙端口（仅 bindPort，业务端口用户自理）

详细设计见 `06-egress-deployment.md` 和根目录 `egress-deployment-design.html`。

## 阶段 2：补认证与角色

目标：

- 统一登录入口
- 注册申请数据落库
- 账号、租户、成员、角色模型落地
- 登录后按角色跳转

### 阶段 2 出口节点体验打磨

- 一行命令安装接口（`GET /e/:token` 返回完整脚本，支持 `curl | bash`）
- `/portal` 安全组图文引导面板（厂商检测 + 端口引导 + 直达链接）
- 端口冲突检测（同主机 bind_port / remote_port 冲突阻止）
- 安装日志实时回显（WebSocket）
- 修复剩余 P1 bug（subDomainHost 映射、proxy 命名稳定、frps SIGTERM）

### 阶段 2 云资源引导推荐

- `/portal` 推荐区：横排厂商优惠卡片，带推广 PID 链接
- `/admin` 推荐管理后台：厂商配置、展示排序、点击统计
- 推荐路径：阿里云（首单优惠）→ 腾讯云（3.5 折）→ 亿速云（30 天免费）→ 我有服务器

详细设计见根目录 `cloud-provisioning-design.html`。

## 阶段 3：补后台和门户的真实接口

目标：

- `/admin` 接概览、租户、平台、发布、Agent
- `/portal` 接客户总览、帮助中心、套餐、AI 入口
- 开始形成真实业务工作台

### 阶段 3 出口节点丝滑体验

- WebSSH 网页终端（xterm.js + ssh2，用户不用开 SSH 客户端）
- 厂商 IP 检测（自动识别阿里云/腾讯云/华为云，展示对应安全组引导）
- Docker 镜像一键部署（`docker run linkio/egress`）
- Windows 出口节点支持
- 出口节点健康度面板（CPU / 内存 / 带宽 / 连接数）

## 阶段 4：补 AI 和多语言

目标：

- AI 映射助手
- AI 排障助手
- AI 发布解释器
- 官网 / 客户端双语
- 后台 i18n key 化

## 阶段 5：商用化收口

目标：

- 接口从方案 A 逐步收成方案 B
- 认证、内容、AI、运营接口统一后端出口
- 增加更正式的审计、套餐、限流、工单、计费收口

### 阶段 5 云资源高级能力（远期）

- 阿里云 OAuth SSO 登录（需企业实名 + ICP 备案）
- RAM 角色跨账号授权引导（配合 OAuth 做一键建机）
- 腾讯云 CAM 子用户/角色引导
- 云市场上架（成为阿里云/腾讯云合作伙伴，拿分销返佣）
- 多云统一管理面板

这些能力需要企业主体资质，且对普通用户来说授权流程过于复杂，留到企业客户阶段再做。

## 当前这轮实现边界

本轮不直接承诺一次性做完整产品，而是先完成：

- 分段设计文档
- 真实入口页面
- NestJS 路由挂载
- 出口节点 MVP（阶段 1 出口节点部分）
- 后续开发的可持续骨架

## 当前事实进度（2026-07）

与本文最初编写时相比，当前仓库的事实进度已经明显前移：

- 阶段 1：已完成
  - 官网、登录、注册、`/admin`、`/portal` 均已可访问
- 阶段 2：主体已完成
  - 认证、注册申请、账号、租户、成员、角色模型已落地
- 阶段 3：主体已完成
  - 后台与门户真实接口已接入，租户、平台、出口、映射、Agent、工单、套餐、计费、审计等模块已具备可用形态
- 阶段 4：部分完成
  - i18n 结构已铺开
  - 已有 AI 映射助手、AI 排障助手初版
  - `AI 发布解释器` 与 `AI 业务日志分析` 尚未完成
- 阶段 5：持续中
  - 审计、套餐、计费、工单、商用化收口已在推进，但仍有新增业务线待并入

因此，当前后续实施重点不再是“把系统做出来”，而是：

- 补齐新业务线 `P2P 节点互联`
- 补齐新业务线 `站点网关`
- 建立统一连接日志中心
- 在日志基础上实现 AI 分析能力

## 新增实施主线：P2P 节点互联

### 总原则

- `P2P 节点互联` 是新增业务线，不替代现有 `公网发布`
- 互联对象是 `Agent ↔ Agent`
- 连接策略是：
  - 优先直连
  - 失败后仅允许回落到 `租户自有公网节点`
- 平台不提供共享中转，不承载租户 P2P 数据面流量

### Impl-P2P-1：PRD 冻结与控制面建模

目标：

- 明确 P2P 业务边界
- 完成数据模型与 API 契约
- 后台增加 P2P 菜单入口

交付：

- `docs/product/07-p2p-agent-connectivity.md`
- 数据库迁移草案
- 后端模块骨架
- 后台占位页面

### Impl-P2P-2：节点、隧道、中转节点

目标：

- 完成 P2P 节点管理
- 完成 P2P 隧道管理
- 完成租户自有公网节点启用为中转节点

交付：

- 节点 CRUD
- 隧道 CRUD
- 中转节点启停
- 租户边界校验

### Impl-P2P-3：连接日志中心

目标：

- 打通 Agent 侧连接事件上报
- 建立结构化连接日志中心
- 支持查询、详情、统计、导出

交付：

- 日志列表
- 日志详情
- 统计面板
- 导出能力

### Impl-P2P-4：直连优先与失败回落

目标：

- NAT 探测
- 直连尝试
- 回落租户自有中转

交付：

- 连接策略实际生效
- 中转调度策略
- 回落原因可观测

### Impl-P2P-5：AI 日志分析 1.0

目标：

- 对 P2P 连接日志做规则型分析
- 输出失败原因、趋势、风险等级和建议动作

交付：

- AI 分析任务
- AI 摘要卡片
- 风险提示
- 审计留痕

## 新增实施主线：站点网关

### 总原则

- `站点网关` 是新增业务线，不替代现有 `公网发布`
- 它也不是 `P2P` 的子页面，而是独立产品线
- 接入对象是：
  - `一个站点`
  - `一个 Gateway Agent`
  - `多个目标设备`
- 第一阶段先支持 `TCP / UDP`
- 第一阶段只支持静态目标登记，不默认开启自动发现

### Impl-SGW-1：PRD 冻结与站点建模

目标：

- 明确站点网关业务边界
- 完成站点、网关、目标设备、站点发布的数据模型与 API 契约
- 后台增加 `站点接入` 菜单入口

交付：

- `docs/product/09-site-gateway.md`
- 数据库迁移草案
- 后端模块骨架
- 后台占位页面

### Impl-SGW-2：站点、网关、目标设备

目标：

- 完成站点 CRUD
- 完成网关绑定
- 完成目标设备 CRUD

交付：

- 站点管理页面
- 网关管理页面
- 目标设备列表与编辑抽屉
- 基础权限校验

### Impl-SGW-3：站点发布与网关转发

目标：

- 完成目标设备映射
- 完成站点发布
- 完成网关目标转发

交付：

- 发布接口
- 目标配置下发
- apply-result 回写
- 发布任务收敛

### Impl-SGW-4：站点健康与告警

目标：

- 网关心跳面板
- 目标可达性摘要
- 站点离线影响范围提示

交付：

- 健康日志
- 统计卡片
- 基础告警提示

### Impl-SGW-5：盒子化交付

目标：

- 支持预装 Gateway Agent 的设备交付
- 降低现场安装难度

交付：

- 盒子初始化流程
- 激活脚本
- 交付手册

## 修订后的进度计划（建议 8 周）

### 第 1 周

- 冻结 P2P PRD
- 冻结站点网关 PRD
- 冻结数据模型
- 冻结页面原型

### 第 2 周

- 完成数据库迁移
- 完成后端骨架
- 完成后台菜单和占位页
- 完成 `站点接入` 模块骨架

### 第 3 周

- 完成节点管理
- 完成隧道管理
- 完成中转节点管理
- 完成站点管理
- 完成网关绑定
- 完成目标设备管理

### 第 4 周

- 完成 Agent 事件上报
- 完成连接日志中心
- 完成统计与导出
- 完成站点发布建模
- 完成网关配置拉取骨架

### 第 5 周

- 完成 NAT 探测
- 完成直连优先与失败回落中转
- 完成中转调度与错误回传
- 完成站点目标转发
- 完成站点发布收敛

### 第 6 周

- 完成 AI 日志分析 1.0
- 完成站点健康日志
- 完成站点离线影响提示

### 第 7 周

- 完成 P2P 联调、压测、灰度、文档收口
- 完成站点网关联调、压测、灰度、文档收口

### 第 8 周

- 评估盒子化交付方案
- 冻结试点站点清单
- 整理客户汇报与交付材料

## 当前优先级重排

从现在开始，优先级建议调整为：

1. 稳住现有 `公网发布` 主线
2. 新增 `P2P 节点互联` 的控制面和日志面
3. 新增 `站点网关` 的站点、网关、目标设备与发布主线
4. 在日志面完成后上线 `AI 日志分析 1.0`
5. 最后再扩展更强的模型型 AI 能力