diff --git a/docs/README.md b/docs/README.md
index 2123ed3..0c4ccfe 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,12 +1,14 @@
 # Fonu 文档索引
 
 > 维护约定：新增方案 / 审查文档时在下方登记；方案落地后在「状态」列标注实施结果，并给已被推翻的描述加时效说明。
-> 最近更新：2026-09-24（v1.2.7）
+> 最近更新：2026-09-27（v1.2.19）
 
 ## 方案与设计（本目录）
 
 | 文件 | 主题 | 状态 |
 | --- | --- | --- |
+| `project-analysis-2026-09-27.md` | 全项目详细分析（v1.2.19）：架构、模块、数据、API、前端、链路、风险与改进路线 | 当前版本快照 |
+| `improvement-roadmap-2026-09-27.md` | P0-P3 改进路线实施方案：逐项改法、测试、验收、依赖、发布与回滚 | P0-1 已完成，其余待实施 |
 | `project-audit-2026-09-24.md` | 全项目审查：P0/P1/P2 分级，含精确行号与逐条修法 | **进行中**——P0 已随 v1.2.7 完成，P1 实施中 |
 | `frp-server-list-merge-plan.md` | FRP 服务端列表并入「公网服务端」页（方案 A，四步） | 步 1/2 已完成（v1.2.6）；步 3 文案收尾、步 4 死样式清理未做 |
 | `agent-capability-plan.md` | fonu-agent 能力扩展（P0/P1/P2/P3） | 已实施（agent 0.11.0）；P3 三项不做 |
diff --git a/docs/improvement-roadmap-2026-09-27.md b/docs/improvement-roadmap-2026-09-27.md
new file mode 100644
index 0000000..047b657
--- /dev/null
+++ b/docs/improvement-roadmap-2026-09-27.md
@@ -0,0 +1,2072 @@
+# Fonu 改进路线实施方案（P0-P3）
+
+> 制定日期：2026-09-27  
+> 适用版本：v1.2.19 之后的迭代  
+> 依据文档：`docs/project-analysis-2026-09-27.md`  
+> 文档性质：实施方案，不代表本轮已经修改代码  
+> 目标：把改进清单拆成可评审、可实施、可验证、可回滚的工程任务
+
+---
+
+## 0. 执行摘要
+
+### 0.1 优先级与目标
+
+| 优先级 | 目标 | 建议周期 | 预计工作量 | 产出 |
+| --- | --- | --- | ---: | --- |
+| P0 | 修复明确问题与安全边界 | 1 个短迭代 | 3-6 人日 | v1.2.x 修复版 |
+| P1 | 降低 FRP、Agent、前端巨型模块风险 | 2-4 个迭代 | 15-25 人日 | 架构重构版 |
+| P2 | 工程质量收口与测试补强 | 与 P1 并行，后续收尾 | 10-18 人日 | 稳定维护版 |
+| P3 | 能力增强 | 独立产品迭代 | 40-70 人日 | v1.3/v1.4 功能版 |
+
+预计工作量为熟悉本项目的一名工程师估算，不包含需求反复、真机环境等待和外部依赖调整。
+
+### 0.2 推荐实施顺序
+
+```text
+M1：P0 修复与安全收口
+  → M2：P1-4 测试基线与 P1-2 文件拆分
+  → M3：P1-1 共享 Nginx 模板
+  → M4：P1-3 前端拆分 + P1-5 轮询统一
+  → M5：P2 工程收口
+  → M6：P3 能力按单项排期
+```
+
+不推荐一次性同时推进 P1、P2、P3。FRP / Agent、前端大组件、数据库性能、迁移包和 2FA 都属于高回归风险区域，必须分批交付。
+
+### 0.3 总体原则
+
+1. **每一步都保持可运行**：先补测试和特征化断言，再做重构。
+2. **优先移动而不是重写**：拆分大文件时先保持函数体不变，只改变文件归属。
+3. **Agent 行为变更必须递增 `AgentVersion`**：并同步重编 amd64、arm64 内嵌二进制。
+4. **数据库变更只向前迁移**：新增迁移从 `028` 开始，不修改已经发布的迁移。
+5. **敏感数据默认不回传**：新增接口必须遵守现有的掩码与“只显示一次”约定。
+6. **新增接口必须有测试**：至少覆盖无鉴权、正常路径、失败路径和兼容路径。
+7. **重构不得顺手改业务语义**：同一 PR 只做一类事情，便于审查和回滚。
+8. **删除前先确认引用**：P2 清理旧代码前，先用 `rg` 证明无运行时引用；删除归档内容需单独确认。
+
+---
+
+## 1. 基线与约束
+
+### 1.1 当前代码基线
+
+| 项目 | 当前值 |
+| --- | --- |
+| 版本 | `1.2.19` |
+| Agent 版本 | `0.12.7` |
+| Go 模块 | `github.com/fonu/fonu` |
+| Go 声明版本 | 1.23 |
+| Go 文件 | 235 个，其中 90 个测试文件 |
+| 内部包 | 29 个 |
+| 数据库迁移 | 27 个 |
+| 受保护 API | 约 113 条 |
+| Agent API | 20 条 `/api/v1/*` |
+| 前端源文件 | 52 个 TypeScript / Vue 文件 |
+| 前端测试 | 2 个 spec、13 条测试 |
+
+### 1.2 当前验证门禁
+
+每次合并前至少执行：
+
+```bash
+go test ./... -count=1
+go vet ./...
+
+cd web
+npm run typecheck
+npm test
+npm run build
+```
+
+涉及 Agent、Docker、Nginx 或跨平台路径时，还需要补：
+
+```bash
+go build ./...
+```
+
+必要时使用 `scripts/build-linux.ps1` 验证 Linux 安装包。
+
+### 1.3 当前已知工程状态
+
+| 项目 | 当前状态 | 影响 |
+| --- | --- | --- |
+| `gofmt -l internal cmd` | 12 个文件未格式化 | 无法立即开启格式化 CI 卡口 |
+| 前端硬编码颜色 | 约 287 处匹配 `#hex`、`rgb()`、`rgba()` | 主题一致性与维护成本 |
+| FRP 主服务 | `internal/frp/service.go` 约 1805 行 | 修改风险集中 |
+| Agent 主服务 | `internal/agent/server.go` 约 1551 行 | HTTP、Nginx、frps、配置写盘耦合 |
+| 前端大页面 | `ProxyView.vue` 约 3150 行 | 组件复用、测试和样式隔离困难 |
+| 工作区 | 有未提交的删除、二进制与品牌图片修改 | 开始迭代前需确认基线提交 |
+
+### 1.4 开始实施前的仓库准备
+
+1. 确认 `Fonu-1.0.2` 内当前未提交改动是否要保留。
+2. 将品牌图片、内嵌 Agent 二进制更新拆成独立提交，避免和功能改动混在一起。
+3. 把 `internal/frp-1.0.2` 与 `FrpView-1.0.2.vue` 的删除单独提交，不与其他重构同批。
+4. 从最新 `main` 建分支，建议前缀 `codex/`。
+5. 所有方案项都从当前 `origin/main` 的已提交状态开始，不基于未确认的工作区改动。
+
+---
+
+## 2. 全局完成定义
+
+### 2.1 单个任务的完成定义
+
+一个任务只有同时满足以下条件才算完成：
+
+- 代码已实现，并保持现有接口兼容；
+- 新增或更新了测试；
+- `go test ./... -count=1` 通过；
+- `go vet ./...` 通过；
+- 前端改动执行 `npm run typecheck`、`npm test`、`npm run build`；
+- Agent 行为变化已递增 `AgentVersion` 并重编双架构二进制；
+- 数据库变化已新增迁移且验证旧库升级；
+- 文档与 `CHANGELOG.md` 已更新；
+- 明确记录回滚方式；
+- 未把无关格式化、品牌资源、二进制替换混入同一提交。
+
+### 2.2 单个 PR 的边界
+
+| PR 类型 | 允许包含 | 不允许包含 |
+| --- | --- | --- |
+| P0 修复 | 单一缺陷、对应测试、必要文档 | 大范围重构、格式化全仓 |
+| 拆分重构 | 文件移动、符号迁移、必要的包内适配 | 行为变化、顺手改接口 |
+| 模板收敛 | 共享纯函数、两组调用方改造、golden 测试 | 顺手改变 Nginx 输出语义 |
+| 前端拆分 | 组件搬迁、props/emits、样式同步搬迁 | 同时重做视觉样式 |
+| 性能优化 | 基准、索引、确认后的连接策略 | 未量化就改 SQLite 配置 |
+| P3 功能 | 迁移、接口、前端、测试、文档 | 多个 P3 功能混在一个 PR |
+
+---
+
+## 3. P0：先处理明确问题
+
+P0 的目标是修复已经确认的缺陷与安全边界，不进行架构大改。
+
+---
+
+## 3.1 P0-1：修正 DDNS 页旧 `/api/frp` 调用
+
+> 实施状态：2026-09-27 已完成。
+
+### 3.1.1 现状
+
+- `web/src/views/DdnsView.vue` 的 `init()` 调用 `api.getFRP()`。
+- `web/src/api/client.ts` 仍保留旧方法：
+  - `getFRP`
+  - `saveFRP`
+  - `getFRPStatus`
+  - `syncFRPDomains`
+  - `getFRPLogs`
+- 后端 `internal/api/router.go` 当前不注册 `/api/frp`，只注册 `/api/frpmulti/*`。
+- `api.getFRP()` 因此失败，进入 `catch`，`frpEnabled.value = false`。
+- DDNS 页顶部“FRP 内网穿透已启用”提示不会正确出现。
+
+### 3.1.2 目标
+
+1. DDNS 页使用当前 FRP 多服务端接口。
+2. 提示只在确实存在可用穿透配置时显示。
+3. 不再依赖已退役的旧 API。
+
+### 3.1.3 实施步骤
+
+1. 将 `DdnsView.vue` 的调用改为：
+
+   ```ts
+   const status = await api.getFrpStatus()
+   frpEnabled.value = status.configured && status.enabled_proxies > 0
+   ```
+
+2. 如产品语义希望“配置了服务端就提示”，可调整为：
+
+   ```ts
+   frpEnabled.value = status.configured
+   ```
+
+   推荐使用 `configured && enabled_proxies > 0`，避免用户刚建服务端但没有任何穿透规则时看到误导提示。
+
+3. 将 `DdnsView.vue` 中 `api.getFRP` 的导入或调用彻底替换。
+4. 暂时保留旧方法不做删除，删除工作纳入 P2-2，避免 P0 同时扩大改动范围。
+
+### 3.1.4 测试
+
+- 前端单元测试：
+  - 新增 `DdnsView` 的辅助纯函数测试，或抽出 `shouldShowFrpHint(status)`。
+  - 覆盖 `configured=false`、`enabled_proxies=0`、`configured=true && enabled_proxies>0`。
+- 手工验证：
+  - 无 FRP 服务端时无提示；
+  - 有服务端但无启用规则时无提示；
+  - 有启用规则时出现提示；
+  - 接口失败时不阻塞 DDNS 页面。
+
+### 3.1.5 验收标准
+
+- `rg -n "api\\.getFRP" web/src/views/DdnsView.vue` 无结果。
+- 页面不再向 `/api/frp` 发请求。
+- DDNS 主要功能在接口异常时仍可加载。
+
+### 3.1.6 风险
+
+| 风险 | 处理 |
+| --- | --- |
+| `getFrpStatus` 返回状态与旧字段不同 | 使用明确映射函数，禁止直接把旧 `enabled` 字段改名为新字段 |
+| 状态接口超时影响页面初始化 | 提示查询与主数据加载分离，失败只影响提示 |
+
+### 3.1.7 实施记录
+
+- `web/src/views/DdnsView.vue` 已改用 `api.getFrpStatus()`。
+- 新增 `web/src/utils/frp.ts`，由 `shouldShowFrpHint` 统一判断“已配置且有启用规则”。
+- 新增 `web/src/utils/frp.spec.ts`，覆盖配置、未配置、无启用规则和空状态。
+- 旧 `/api/frp` 客户端方法尚未删除，按要求留到 P2-2 统一清理。
+- 验证通过：`npm test` 17 条、`npm run typecheck`、`npm run build`。
+
+---
+
+## 3.2 P0-2：初始管理员密码不再写入持久应用日志
+
+### 3.2.1 现状
+
+- `internal/auth/auth.go` 的 `EnsureDefaultAdmin` 使用 `slog` 记录用户名和密码。
+- `internal/app/app.go` 的日志同时写入 stdout 和 `<DataDir>/logs/app.log`。
+- `internal/logstore/display.go` 的 `appendSystemAttrs` 专门把初始密码渲染进系统日志。
+- `internal/api/logs_handler.go` 的 `/api/logs/system` 会读取 `app.log`。
+- `scripts/fonu-install.sh` 当前从 `app.log` 中提取初始密码。
+
+这意味着“初始密码只出现一次”的现实边界并不成立，密码会长期留在数据目录日志中。
+
+### 3.2.2 目标
+
+1. 初始密码只在首次启动时输出一次。
+2. 默认输出到进程 stdout/stderr，不写入 `app.log`。
+3. Docker 用户可通过 `docker logs fonu` 获取。
+4. systemd 用户可通过 `journalctl -u fonu` 获取。
+5. 安装脚本改为从 journal 或服务日志读取，不再读取 `app.log`。
+6. 日志中心不再能读到初始密码。
+
+### 3.2.3 推荐设计
+
+修改 `auth.Service.EnsureDefaultAdmin`：
+
+```go
+type BootstrapAdmin struct {
+    Username string
+    Password string
+    Created  bool
+}
+
+func (s *Service) EnsureDefaultAdmin(ctx context.Context) (BootstrapAdmin, error)
+```
+
+- `Created=false` 时不返回密码。
+- 不在 `auth` 包内部写密码日志。
+- `app.New` 收到 `Created=true` 后，使用独立的 `os.Stderr` 或标准输出直接打印，不经过 `slog` 的 `MultiWriter`。
+
+示例输出：
+
+```text
+Fonu 首次启动已创建管理员账户
+用户名：admin
+初始密码：<一次性密码>
+请登录后立即修改密码。
+```
+
+### 3.2.4 实施步骤
+
+1. 重构 `EnsureDefaultAdmin` 返回值。
+2. `app.New` 调整调用与一次性输出。
+3. 删除 `logstore.appendSystemAttrs` 中初始密码的特殊拼接分支。
+4. 更新 `logstore/display_test.go`，断言日志中出现初始密码构建消息时不再拼接 `password`。
+5. 更新 `scripts/fonu-install.sh`：
+   - 删除从 `app.log` grep 密码的逻辑；
+   - 改为读取 `journalctl -u fonu` 最近日志；
+   - 如果服务尚未写入日志，则提示用户执行 `journalctl` 或 `docker logs`。
+6. 更新 Docker、原生安装和 FAQ 文档。
+
+### 3.2.5 测试
+
+- `internal/auth/auth_test.go`
+  - 首次创建返回 `Created=true` 且有密码；
+  - 第二次调用返回 `Created=false` 且无密码。
+- `internal/app` 测试或日志测试：
+  - `app.log` 不包含初始密码；
+  - 标准输出可以包含一次初始密码。
+- `internal/logstore/display_test.go`
+  - 系统日志渲染不再输出 `password`。
+- shell 验证：
+  - 原生安装后 `journalctl -u fonu` 能读到初始密码；
+  - `app.log` 中 grep 不到初始密码。
+
+### 3.2.6 验收标准
+
+- `<DataDir>/logs/app.log` 中不出现初始密码。
+- `/api/logs/system` 响应中不出现初始密码。
+- 安装脚本仍能提示首次密码。
+- 已初始化实例不受影响。
+
+### 3.2.7 兼容与回滚
+
+- 已存在的日志不会被自动清理；可增加“安全清理旧日志”的手工建议，不在代码中自动删除。
+- 回滚仅恢复日志输出方式，不影响管理员数据。
+- 该修复不要求 Agent 升级。
+
+---
+
+## 3.3 P0-3：Agent Token 使用常量时间比较
+
+### 3.3.1 现状
+
+`internal/agent/server.go` 的 `auth` 方法使用普通字符串比较：
+
+```go
+if r.Header.Get("Authorization") != "Bearer "+s.cfg.Token {
+```
+
+这不是直接可利用漏洞，但不符合安全敏感的 Token 比较约定。
+
+### 3.3.2 目标
+
+将 Bearer Token 解析成独立函数，并使用 `crypto/subtle.ConstantTimeCompare`。
+
+### 3.3.3 推荐实现
+
+```go
+func bearerToken(r *http.Request) string {
+    header := strings.TrimSpace(r.Header.Get("Authorization"))
+    const prefix = "Bearer "
+    if len(header) <= len(prefix) || !strings.EqualFold(header[:len(prefix)], prefix) {
+        return ""
+    }
+    return strings.TrimSpace(header[len(prefix):])
+}
+
+func secureEqual(got, want string) bool {
+    return subtle.ConstantTimeCompare([]byte(got), []byte(want)) == 1
+}
+```
+
+`auth` 方法：
+
+```go
+token := bearerToken(r)
+if token == "" || !secureEqual(token, s.cfg.Token) {
+    writeJSON(w, http.StatusUnauthorized, map[string]string{"error": "unauthorized"})
+    return
+}
+```
+
+### 3.3.4 测试
+
+新增 `internal/agent/auth_test.go`：
+
+- 正确 Token 返回 200；
+- 错误 Token 返回 401；
+- 缺失 Authorization 返回 401；
+- `bearer` 大小写兼容；
+- 多空格处理；
+- 长度不同时不 panic。
+
+### 3.3.5 验收标准
+
+- 所有 Agent 接口仍使用相同 Bearer Token。
+- 正确 Token 通过，错误 Token 拒绝。
+- Agent 不依赖应用侧 API 中间件代码。
+
+---
+
+## 3.4 P0-4：限流状态解析失败时拒绝覆盖原状态
+
+### 3.4.1 现状
+
+`internal/agent/server.go` 的 `readLimitState`：
+
+```go
+_ = json.Unmarshal(data, &state)
+return state
+```
+
+如果 `route-limits.json` 损坏：
+
+1. 返回空 map；
+2. `applyLimitState` 只写入当前域名；
+3. `writeLimitState` 用不完整状态覆盖原文件；
+4. 其他域名的限流配置丢失。
+
+### 3.4.2 目标
+
+- 文件不存在：返回空状态，不报错。
+- 文件存在但读取失败或 JSON 损坏：返回错误，不继续写。
+- 调用方把错误回传到 HTTP 502/500，保留原文件和现有 Nginx zone。
+
+### 3.4.3 推荐接口
+
+```go
+func readLimitState() (map[string]routeLimit, error)
+
+func (s *Server) applyLimitState(req routeRequest) error
+func (s *Server) clearLimitState(domain string) error
+```
+
+建议错误文案：
+
+```text
+读取限流状态失败: /var/lib/fonu-agent/route-limits.json: <原因>
+```
+
+### 3.4.4 实施步骤
+
+1. 修改 `readLimitState` 返回 `(map, error)`。
+2. `os.IsNotExist` 返回空 map 和 nil。
+3. `os.ReadFile` 其他错误返回错误。
+4. `json.Unmarshal` 错误返回错误。
+5. `applyLimitState`、`clearLimitState` 直接传播错误。
+6. 新增测试：
+   - 文件不存在；
+   - 空对象；
+   - 正常对象；
+   - 截断 JSON；
+   - 类型错误；
+   - 解析失败时原文件内容不变。
+7. 可选：在损坏时先生成 `.corrupt-<timestamp>` 快照，但不得自动删除原文件。
+
+### 3.4.5 验收标准
+
+- 损坏状态不会导致其他域名限流配置被清空。
+- 错误能显示在“应用配置”或路由保存响应中。
+- `nginx -t` 仍以真实生成结果为准。
+
+---
+
+## 3.5 P0-5：明确 Agent 默认监听策略
+
+### 3.5.1 现状
+
+- `cmd/fonu-agent/main.go` 默认 `:7700`。
+- `internal/agent.NewServer` 空配置时也回落到 `:7700`。
+- `scripts/agent-install.sh` 的 systemd 单位只设置环境文件，不显式限制监听地址。
+- Agent 当前为明文 HTTP，Bearer Token 在网络中裸传。
+- 安装脚本打印 `http://<host-ip>:7700`，鼓励直接公网访问。
+
+### 3.5.2 策略选择
+
+推荐采用两阶段策略，避免一次性破坏现有部署：
+
+#### 阶段 A：先警告与显式标记
+
+适用于下一个修复版本：
+
+1. Agent 状态接口增加：
+   - `listen_addr`
+   - `transport_scheme`
+   - `transport_secure`
+   - `security_warning`
+2. 当监听非环回地址且未启用 TLS 时：
+   - 启动日志打印醒目的中文警告；
+   - 前端“公网服务端”页展示警告；
+   - 安装脚本提示必须使用 Nginx HTTPS 或 SSH 隧道；
+   - 不立即阻止启动。
+
+#### 阶段 B：默认仅本机，显式允许远程
+
+适用于一个明确的 minor 版本：
+
+1. 默认监听改为 `127.0.0.1:7700`。
+2. 新增 `FONU_AGENT_ALLOW_REMOTE=1` 或 `-allow-remote`：
+   - 没有该显式选项时，拒绝监听非环回地址。
+3. 新增可选直接 TLS：
+   - `FONU_AGENT_TLS_CERT`
+   - `FONU_AGENT_TLS_KEY`
+4. 非环回监听满足以下任一条件才允许：
+   - TLS 证书和私钥已配置；
+   - 明确使用 `--insecure-allow-http` 并打印高危警告。
+5. 安装脚本默认写入：
+
+   ```dotenv
+   FONU_AGENT_LISTEN=127.0.0.1:7700
+   ```
+
+6. 如用户选择远程模式，安装脚本引导配置 Nginx HTTPS 反向代理，或写入显式不安全开关。
+
+### 3.5.3 中央 Fonu 的连接方式
+
+推荐远程连接路径：
+
+```text
+Fonu 控制面
+  → https://agent.example.com
+  → VPS Nginx 443
+  → 127.0.0.1:7700 fonu-agent
+```
+
+备选路径：
+
+```text
+Fonu 控制面
+  → SSH 本地转发或 WireGuard
+  → 127.0.0.1:7700 fonu-agent
+```
+
+不推荐：
+
+```text
+Fonu 控制面
+  → http://公网IP:7700
+```
+
+### 3.5.4 前端与接口变化
+
+1. `AgentView.vue` 状态卡增加“传输安全”字段。
+2. 当 `transport_secure=false` 且监听地址非本机时，显示橙色警告。
+3. 安装脚本输出改为：
+
+   ```text
+   Agent 默认仅监听 127.0.0.1:7700。
+   如需远程连接，请先配置 HTTPS 反向代理，再设置 FONU_AGENT_ALLOW_REMOTE=1。
+   ```
+
+### 3.5.5 兼容迁移
+
+升级已有 Agent 时：
+
+1. 保留 `/etc/fonu-agent/agent.env`。
+2. 旧配置未设置 `FONU_AGENT_LISTEN` 时：
+   - 阶段 A 继续使用旧默认值；
+   - 阶段 B 给出迁移提示，并在一个过渡版本内保持旧行为。
+3. 新安装默认 loopback。
+4. 如果旧部署使用公网 `:7700`，升级说明必须明确如何加 Nginx HTTPS。
+5. `agent_url` 当前是 `http://` 时，前端显示不安全提示。
+
+### 3.5.6 测试
+
+- 默认启动监听 loopback。
+- 非环回监听无显式允许时拒绝启动。
+- `--insecure-allow-http` 时启动并输出警告。
+- 配置 TLS 时启动 HTTPS。
+- 安装脚本生成的环境文件符合所选模式。
+- 旧环境文件升级不丢 Token。
+
+### 3.5.7 验收标准
+
+- 新安装不会默认暴露明文 Agent 到公网。
+- 用户仍可通过明确配置保留远程管理能力。
+- 文档给出 Nginx HTTPS 与 SSH 隧道两种方案。
+- 安全状态在前端可见。
+
+---
+
+## 4. P1：降低核心模块风险
+
+P1 的核心是控制复杂度，不改变可见功能。
+
+---
+
+## 4.1 P1-1：抽共享 Nginx 模板包
+
+### 4.1.1 现状
+
+本机与公网 Agent 各有一套 Nginx 生成逻辑：
+
+| 位置 | 用途 |
+| --- | --- |
+| `internal/nginx/generate.go` | 本机反代主配置与规则块 |
+| `internal/nginx/security.go` | 本机安全、限流、geo、TLS |
+| `internal/agent/server.go` 的 `nginxRoute` | VPS vhost |
+| `internal/agent/server.go` 的 `sslDirectives` | VPS TLS |
+| `internal/agent/server.go` 的 `zoneKey` / `writeLimitState` | VPS 限流 zone |
+
+同一类安全问题需要改两处，容易漂移。
+
+### 4.1.2 共享边界
+
+新建纯生成包，建议命名：
+
+```text
+internal/nginxtmpl
+```
+
+该包只负责把结构化参数渲染成字符串，不依赖：
+
+- `internal/proxy`
+- `internal/config`
+- `internal/frp`
+- `internal/agent`
+- 文件系统
+- 进程执行
+
+这样 `internal/nginx` 和 `internal/agent` 都可以安全导入，不会循环依赖。
+
+### 4.1.3 建议 API
+
+```go
+package nginxtmpl
+
+type TLSConfig struct {
+    CertPath  string
+    KeyPath   string
+    TLS13Only bool
+}
+
+type AccessControl struct {
+    Allow     []string
+    Deny      []string
+    ChinaOnly bool
+}
+
+type LimitConfig struct {
+    Zone  string
+    Rate  int
+    Burst int
+    Conn  int
+}
+
+type SecurityHeaders struct {
+    HTTPS          bool
+    Enabled        bool
+    HSTSMaxAgeDays int
+}
+
+func SSLDirectives(cfg TLSConfig) string
+func ServerSecurityHeaders(cfg SecurityHeaders) string
+func AccessDirectives(cfg AccessControl, indent string) string
+func LimitDirectives(cfg LimitConfig, indent string) string
+func RateLimitZone(zone string, rate int) string
+func ConnLimitZone(zone string) string
+func ZoneName(prefix string, parts ...string) string
+```
+
+### 4.1.4 先做特征化测试
+
+在改动前，为两份输出增加或固定以下测试：
+
+- HTTPS 证书指令；
+- TLS 1.3 开关；
+- HSTS 与安全响应头；
+- allow / deny 顺序；
+- 白名单末尾 `deny all`；
+- WebSocket Upgrade 头；
+- 限流与连接数指令；
+- 中国 IP geo 变量；
+- 错误页 location；
+- 空参数不输出多余指令。
+
+这些测试先锁定现有语义，再替换为共享函数。
+
+### 4.1.5 实施步骤
+
+1. 新增 `internal/nginxtmpl`。
+2. 先迁出无业务依赖的函数：
+   - TLS 指令；
+   - 安全响应头；
+   - allow / deny；
+   - WebSocket 头；
+   - zone 命名。
+3. 本机 `internal/nginx` 改为调用共享函数，保持输出逐字节一致。
+4. Agent `nginxRoute` 分阶段改为调用共享函数。
+5. 为中国 IP 仅大陆规则保留差异适配层：
+   - 本机使用 `geo $fonu_client_ip` 与规则 ID 变量；
+   - Agent 使用 `$fonu_china_client`；
+   - 两者共享 allow/deny 与返回 403 结构，不强行共享变量名。
+6. 删除重复实现，但保留本机与 Agent 各自的上下文拼装函数。
+
+### 4.1.6 验收标准
+
+- 同一参数在两端的 TLS、安全头、WebSocket、限流输出一致。
+- `internal/agent` 不再自行实现通用 TLS 指令。
+- 两端测试均可独立覆盖共享模板。
+- 本机 Nginx 与 Agent 生成内容没有未解释的语义变化。
+
+### 4.1.7 风险
+
+| 风险 | 处理 |
+| --- | --- |
+| 两端缩进与上下文不同 | 共享函数接受 `indent`，不强制服务块结构 |
+| Agent 使用域名 zone，本机使用规则 ID | `ZoneName` 只负责合法化，不负责决定命名规则 |
+| 修改模板导致现有 vhost 重写 | 先做 golden 对比，再在部署时保留版本回滚 |
+
+---
+
+## 4.2 P1-2：拆分 `internal/frp/service.go` 与 `internal/agent/server.go`
+
+### 4.2.1 拆分原则
+
+1. 同一 Go 包内拆文件，不改变外部接口。
+2. 只移动函数、类型和常量，不重写逻辑。
+3. 每个文件目标 300-500 行以内。
+4. 每个函数继续遵守函数长度不超过 50 行的仓库约定。
+5. 拆分后先跑全量测试，再做后续优化。
+
+### 4.2.2 `internal/frp` 目标文件
+
+| 新文件 | 责任 |
+| --- | --- |
+| `service.go` | Service 结构、构造、公共装配 |
+| `service_servers.go` | 服务端 CRUD、配置保存、凭证与 TLS 资产 |
+| `service_proxies.go` | 穿透规则 CRUD、列表、日志 |
+| `service_runtime.go` | frpc 启动、停止、重载、状态、自动恢复 |
+| `service_download.go` | 版本列表、下载任务、二进制激活与清理 |
+| `service_diagnostics.go` | 服务端五项诊断与延迟记录 |
+| `service_agent_lifecycle.go` | SSH 安装、升级、卸载、Probe、急救诊断 |
+| `service_agent_routes.go` | vhost 部署、删除、漂移、版本与证书推送 |
+| `service_health.go` | 规则健康、可用率、汇总 |
+| `service_config.go` | frpc.toml / frps.toml 渲染与原子写 |
+| `service_traffic.go` | frps dashboard 流量适配 |
+
+### 4.2.3 `internal/agent` 目标文件
+
+| 新文件 | 责任 |
+| --- | --- |
+| `server.go` | Config、Server、NewServer、路由注册、ListenAndServe |
+| `auth.go` | Bearer Token 解析与常量时间比较 |
+| `handlers_status.go` | ping、status、metrics 状态输出 |
+| `handlers_routes.go` | route CRUD、conf、版本、回滚 |
+| `handlers_nginx.go` | Nginx 探测、安装、校验、重载、日志 |
+| `handlers_frps.go` | frps 配置、安装、启停、日志 |
+| `handlers_certs.go` | 证书写入与列表 |
+| `handlers_china.go` | 中国 IP 段写入与 geo 文件生成 |
+| `limits.go` | route-limits.json、zone 文件、限流状态 |
+| `nginx_template.go` | Agent vhost 模板拼装 |
+| `path_detect.go` | Nginx 目录、可执行文件与版本探测 |
+| `basic_auth.go` | htpasswd 生成与复用 |
+
+### 4.2.4 拆分顺序
+
+1. 先拆 `internal/frp` 中低耦合的下载、诊断、健康文件。
+2. 再拆服务端 CRUD 与运行管理。
+3. 最后拆 Agent 生命周期与路由部署。
+4. `internal/agent` 先拆 auth、limits、handlers_nginx，再拆 routes。
+5. 每拆一组文件执行：
+
+   ```bash
+   go test ./internal/frp ./internal/agent -count=1
+   go test ./... -count=1
+   ```
+
+### 4.2.5 验收标准
+
+- 包外 API 没有变化。
+- 没有新增循环依赖。
+- 测试结果与拆分前一致。
+- 文件行数显著下降，主文件不再承担所有职责。
+- 行为变更与文件移动没有混在同一 PR。
+
+---
+
+## 4.3 P1-3：拆分前端巨型页面
+
+### 4.3.1 拆分原则
+
+1. 组件只接收 props，通过 emits 通知父页面。
+2. 网络请求留在页面或 composable 中，避免弹窗组件私自保存。
+3. scoped 样式必须随模板一起搬迁。
+4. 每次只拆一个页面，先拆纯展示区域，再拆表单。
+5. 拆分后视觉应与原页面一致。
+
+### 4.3.2 `ProxyView.vue` 拆分建议
+
+| 新组件 / composable | 责任 |
+| --- | --- |
+| `ProxyRuleFormModal.vue` | 新建/编辑表单、基础/安全/Nginx 三个页签 |
+| `ProxyRuleDetailModal.vue` | 规则详情、概览与日志 |
+| `ProxyClientsPanel.vue` | 当前连接与客户端 IP |
+| `ProxyNginxPanel.vue` | 自动/自定义配置、版本与回滚 |
+| `useProxyRules.ts` | 列表、保存、删除、排序 |
+| `useProxyTraffic.ts` | 流量与在线连接轮询 |
+
+### 4.3.3 `SettingsView.vue` 拆分建议
+
+| 新组件 / composable | 责任 |
+| --- | --- |
+| `SettingsGeneralPanel.vue` | 主题、时区、日志、DDNS、证书默认值 |
+| `SettingsNotificationsPanel.vue` | 通知渠道与告警事件 |
+| `SettingsSecurityPanel.vue` | 登录失败、全局 IP 策略、信任代理 |
+| `SettingsAdvancedPanel.vue` | 中国 IP、Nginx 主配置、状态页、指标 |
+| `BackupPanel.vue` | 立即备份、归档、恢复、删除 |
+| `ApiTokensPanel.vue` | Token 创建、范围、有效期、撤销 |
+| `useSettingsForm.ts` | 设置加载、脏状态、保存与掩码字段 |
+
+### 4.3.4 `AgentView.vue` 拆分建议
+
+| 新组件 / composable | 责任 |
+| --- | --- |
+| `AgentServerFormModal.vue` | 服务端、Agent、SSH、frps 配置表单 |
+| `AgentServerDetailModal.vue` | 详情、frps 同源配置、控制入口 |
+| `AgentServerLogsModal.vue` | Agent / frps 日志 |
+| `AgentDiagnosticsPanel.vue` | 五项诊断与可用率 |
+| `AgentMetricsPanel.vue` | 资源、延迟、日志和证书 |
+| `useAgentServers.ts` | 列表、选择、加载、生命周期调用 |
+| `useAgentPolling.ts` | 状态与诊断轮询 |
+
+### 4.3.5 测试与验证
+
+- 拆分后保留原有交互路径。
+- 为 props/emits 增加 `@vue/test-utils` 测试。
+- 使用 Playwright 对桌面与移动视口截图：
+  - `/proxies`
+  - `/settings`
+  - `/frp-agent`
+- 检查弹窗尺寸、滚动区域、按钮位置、移动端文本溢出。
+- 检查 `vue-tsc` 与 `vite build`。
+
+### 4.3.6 验收标准
+
+- 单个页面文件不再超过约 1200 行。
+- 新组件职责单一，父页面只负责协调。
+- 原页面的交互和视觉不变。
+- 拆分过程中未丢失 scoped 样式。
+
+---
+
+## 4.4 P1-4：补路由鉴权、配置回滚、Agent 版本兼容测试
+
+### 4.4.1 路由鉴权覆盖测试
+
+目标：防止新增 API 时漏掉 `protect()`。
+
+建议改造 `internal/api/router.go`：
+
+```go
+type routeSpec struct {
+    Method   string
+    Pattern  string
+    Handler  http.HandlerFunc
+    Public   bool
+    TokenDeny bool
+}
+```
+
+- 构造统一路由表；
+- 注册循环只负责挂载与包中间件；
+- 测试直接遍历路由表；
+- 对受保护路由发匿名请求，期望 401；
+- 对公开路由断言不因鉴权而 401。
+
+测试文件：
+
+```text
+internal/api/router_auth_test.go
+```
+
+Agent 同样增加：
+
+```text
+internal/agent/router_auth_test.go
+```
+
+遍历 20 个 `/api/v1/*` 路径，无 Bearer Token 必须返回 401。
+
+### 4.4.2 配置回滚测试
+
+覆盖本机：
+
+- `internal/nginx/versions.go` 的版本列表、读取、回滚；
+- 非法版本名拒绝路径上跳；
+- 回滚时先校验语法；
+- 新配置校验失败时不覆盖当前配置；
+- `fsutil.BackupVersioned` 去重逻辑。
+
+覆盖 Agent：
+
+- 写 vhost 前保存版本；
+- `nginx -t` 失败后恢复上一可用版本；
+- 首次部署失败时删除新文件而不破坏已有文件；
+- 回滚接口调用后执行 `nginx -s reload`；
+- 旧 Agent 无版本接口时返回升级提示。
+
+建议测试文件：
+
+```text
+internal/nginx/versions_test.go
+internal/agent/versions_test.go
+internal/frp/agent_versions_compat_test.go
+```
+
+### 4.4.3 Agent 版本兼容测试
+
+建立最低版本矩阵：
+
+| 能力 | 最低 Agent 版本 |
+| --- | --- |
+| 基础状态 / 路由 | 现有最低版本 |
+| metrics / logs / frps-config | 0.11.0 |
+| route versions / rollback | 0.12.2 |
+| 新版安全监听策略 | 新版本 |
+
+测试内容：
+
+- `AgentClient` 遇到 404 / 405 返回 `ErrAgentEndpointMissing`；
+- 错误信息包含最低版本和升级提示；
+- 其他 4xx / 5xx 不误判为版本过低；
+- 状态接口返回 `agent_version` 后可正确展示；
+- 新字段缺失时前端降级，不显示空白页。
+
+### 4.4.4 验收标准
+
+- 新增受保护路由漏鉴权时，测试会失败。
+- 配置回滚失败不会覆盖当前可用配置。
+- 旧 Agent 与新控制端组合时有明确提示，不崩溃。
+
+---
+
+## 4.5 P1-5：统一前端轮询组合式函数
+
+### 4.5.1 现状
+
+已有 `web/src/composables/useVisibilityPolling.ts`，并被：
+
+- `ProxyRemoteView.vue`
+- `FrpView.vue`
+
+使用，但其他页面仍自行维护计时器：
+
+- `DashboardView.vue`
+- `ProxyView.vue`
+- `LogsView.vue`
+- `AgentView.vue`
+- `SettingsView.vue` 的中国 IP 状态轮询
+
+当前 composable 没有 in-flight 互斥，慢请求仍可能堆积。
+
+### 4.5.2 目标
+
+统一行为：
+
+1. 页面隐藏时暂停；
+2. 回到前台立即补一次；
+3. 上一轮未结束时跳过下一轮；
+4. 支持 `enabled` 开关；
+5. 组件卸载时清理；
+6. 可选 `immediate` 立即执行；
+7. 返回 `busy` 状态，便于 UI 展示。
+
+### 4.5.3 建议 API
+
+```ts
+export interface VisibilityPollingOptions {
+  enabled?: Ref<boolean>
+  immediate?: boolean
+  onError?: (error: unknown) => void
+}
+
+export function useVisibilityPolling(
+  fn: () => void | Promise<void>,
+  intervalMs: number,
+  options: VisibilityPollingOptions = {},
+) {
+  // return { start, stop, busy, lastError }
+}
+```
+
+### 4.5.4 实施步骤
+
+1. 更新 composable，增加 in-flight 锁。
+2. `tick()` 中：
+
+   ```ts
+   if (busy.value) return
+   busy.value = true
+   Promise.resolve(fn())
+     .catch(onError)
+     .finally(() => { busy.value = false })
+   ```
+
+3. 将页面手动计时器替换为 composable。
+4. 页面已有的“首次加载”和“轮询”分开：
+   - 首次加载立即执行；
+   - 轮询只刷新增量或状态。
+5. SSE 日志不纳入轮询 composable。
+
+### 4.5.5 测试
+
+- 隐藏时不执行；
+- 回到前台执行一次；
+- 请求未结束时跳过下一轮；
+- `enabled=false` 不执行；
+- 卸载后无计时器；
+- `onError` 被调用且不影响后续轮询。
+
+### 4.5.6 验收标准
+
+- 各页面不再重复实现 `setInterval + visibilitychange`。
+- 慢接口不会产生请求堆积。
+- 页面前后台切换行为一致。
+
+---
+
+## 5. P2：工程质量提升
+
+P2 的重点是减少噪音、建立长期质量门禁，不改变大功能。
+
+---
+
+## 5.1 P2-1：全仓 `gofmt` 与 CI 卡口
+
+### 5.1.1 当前结果
+
+执行：
+
+```bash
+gofmt -l internal cmd
+```
+
+当前仍有未格式化文件，包括：
+
+- `internal/acme/job.go`
+- `internal/api/auth_handler_test.go`
+- `internal/api/logs_handler_test.go`
+- `internal/api/version_handler.go`
+- `internal/ddns/store.go`
+- `internal/ddns/tencentcloud_test.go`
+- `internal/frp/diagnostics.go`
+- `internal/frp/store.go`
+- `internal/nginx/generate_multi_test.go`
+- `internal/nginx/generate_seed_mix_test.go`
+- `internal/nginx/realip.go`
+- `internal/nginx/security.go`
+
+### 5.1.2 实施步骤
+
+1. 单独创建“格式化”提交。
+2. 执行：
+
+   ```bash
+   gofmt -w ./cmd ./internal
+   ```
+
+3. 检查 diff，确认只有格式变化。
+4. 运行：
+
+   ```bash
+   go test ./... -count=1
+   go vet ./...
+   ```
+
+5. 在 `.github/workflows/ci.yml` 的 `go vet` 前增加：
+
+   ```yaml
+   - name: gofmt
+     run: test -z "$(gofmt -l ./cmd ./internal)"
+   ```
+
+### 5.1.3 验收标准
+
+- `gofmt -l internal cmd` 无输出。
+- CI 对后续未格式化文件立即失败。
+- 格式化 PR 不包含业务逻辑变化。
+
+---
+
+## 5.2 P2-2：清理旧 FRP 类型、旧 API 方法与未使用样式
+
+### 5.2.1 旧 API 清理
+
+目标：
+
+- `web/src/api/client.ts` 删除：
+  - `getFRP`
+  - `saveFRP`
+  - `getFRPStatus`
+  - `syncFRPDomains`
+  - `getFRPLogs`
+- `web/src/api/types.ts` 删除不再使用的旧接口：
+  - `FRPConfig`
+  - `FRPResponse`
+  - `FRPSaveResponse`
+  - `FRPSavePayload`
+  - 以及只服务旧 `/api/frp` 的 `FRPStatus`
+
+注意：`FrpStatus` 这个名字与多服务端 `FrpStatus` 有潜在冲突，清理时先确认类型引用。
+
+### 5.2.2 前端样式清理流程
+
+1. 枚举模板中的 class；
+2. 与 `<style scoped>` 中定义对比；
+3. 标记只出现在样式、不出现在模板与脚本中的类；
+4. 人工确认动态 class：
+   - `:class="{ ... }"`
+   - 字符串拼接；
+   - `:deep()`；
+5. 删除确认无用的样式块；
+6. 每次只清理一个页面；
+7. 截图对比删除前后。
+
+重点页面：
+
+- `FrpView.vue`
+- `AgentView.vue`
+- `ProxyView.vue`
+- `ProxyRemoteView.vue`
+
+### 5.2.3 验收标准
+
+- `rg -n "/api/frp\\b" web/src internal` 不再包含旧路由调用。
+- `vue-tsc` 无 unused 报错。
+- 页面视觉无回归。
+- 删除项有明确引用证明。
+
+---
+
+## 5.3 P2-3：收敛颜色令牌与重复弹窗外壳
+
+### 5.3.1 颜色令牌
+
+当前匹配 `#hex`、`rgb()`、`rgba()`、`color-mix()` 约 287 处。建议在 `web/src/styles/variables.css` 增加语义令牌：
+
+```css
+--fonu-tone-info
+--fonu-tone-success
+--fonu-tone-warning
+--fonu-tone-error
+
+--fonu-tone-info-soft
+--fonu-tone-success-soft
+--fonu-tone-warning-soft
+--fonu-tone-error-soft
+
+--fonu-log-bg
+--fonu-log-text
+--fonu-log-success
+--fonu-log-warning
+--fonu-log-error
+
+--fonu-chart-1
+--fonu-chart-2
+--fonu-chart-3
+--fonu-chart-4
+--fonu-chart-5
+--fonu-chart-6
+```
+
+替换顺序：
+
+1. `StatCard`、`StatusBadge`；
+2. 仪表盘横幅；
+3. 证书、DDNS、反代状态色；
+4. 日志终端色；
+5. 图表色板；
+6. 零散页面。
+
+### 5.3.2 弹窗外壳
+
+新增 `web/src/components/ProxyModalShell.vue`：
+
+| 插槽 | 内容 |
+| --- | --- |
+| `header` | 标题、状态、关闭按钮 |
+| `tabs` | 可选页签 |
+| `default` | 滚动内容 |
+| `footer` | 保存、取消 |
+| `help` | 右侧或底部说明面板 |
+
+使用页面：
+
+- `ProxyView.vue`
+- `FrpView.vue`
+- `ProxyRemoteView.vue`
+- `AgentView.vue`
+
+### 5.3.3 左侧列表
+
+新增 `SidebarList.vue`：
+
+- `items`
+- `activeKey`
+- `loading`
+- `emptyText`
+- `item` 插槽
+- `header` 插槽
+
+先替换同构的：
+
+- `FrpView.vue`
+- `AgentView.vue`
+- `ProxyRemoteView.vue`
+- `DdnsView.vue`
+
+### 5.3.4 验收标准
+
+- 新增颜色优先使用语义令牌。
+- 弹窗外壳不再在四个页面各自复制。
+- 暗色模式与亮色模式截图一致。
+
+---
+
+## 5.4 P2-4：前端 API 客户端测试与关键组件测试
+
+### 5.4.1 测试环境
+
+新增开发依赖：
+
+```text
+@vue/test-utils
+happy-dom
+```
+
+Vitest 配置使用 `happy-dom`，避免引入完整浏览器。
+
+### 5.4.2 API 客户端测试
+
+测试 `web/src/api/client.ts`：
+
+- 204 返回 `undefined`；
+- 非 2xx 解析 JSON error；
+- 非 JSON 错误回退；
+- 30 秒超时；
+- 证书 10 分钟超时；
+- `credentials: include`；
+- `asList` 对 null / undefined 的处理；
+- Blob 下载解析文件名。
+
+建议 mock `global.fetch`，使用 `vi.useFakeTimers()` 控制超时。
+
+### 5.4.3 组件测试
+
+优先测试纯组件和共用组件：
+
+- `StatusBadge.vue`
+- `StatCard.vue`
+- `FonCard.vue`
+- `EmptyState.vue`
+- `ConfiguredSecretField.vue`
+- `ConfigDiffView.vue`
+- `ProxyModalShell.vue`
+- `SidebarList.vue`
+
+页面拆分后，再测试：
+
+- `ProxyRuleFormModal`
+- `SettingsNotificationsPanel`
+- `AgentServerFormModal`
+
+### 5.4.4 验收标准
+
+- `npm test` 在 CI 中运行。
+- 新增组件必须有测试或明确说明为何不测。
+- 关键错误路径有前端断言，而不是只依赖手工点击。
+
+---
+
+## 5.5 P2-5：SQLite 高频查询基准与单连接评估
+
+### 5.5.1 当前配置
+
+`internal/db/db.go`：
+
+```go
+conn.SetMaxOpenConns(1)
+```
+
+优点是避免写锁冲突，缺点是所有读写串行。
+
+### 5.5.2 基准目录
+
+新增：
+
+```text
+internal/db/benchmark_test.go
+internal/db/fixture_test.go
+```
+
+或放在对应包：
+
+```text
+internal/metrics/benchmark_test.go
+internal/frp/health_benchmark_test.go
+internal/proxy/benchmark_test.go
+```
+
+### 5.5.3 基准场景
+
+| 场景 | 数据量 | 目标 |
+| --- | ---: | --- |
+| 24 小时指标查询 | 约 7,920 点 | < 100ms |
+| 7 天指标查询、720 桶 | 约 55,440 点 | < 250ms |
+| 100 条反代规则列表 | 100 规则 | < 50ms |
+| 规则可用率推导 | 30 天状态变化 | < 100ms |
+| 日志分页 | 10 万行 | < 200ms |
+| 并发读 8 / 写 1 | 60 秒 | 无 `database is locked` |
+
+目标值基于常见 NAS CPU，具体以项目基准环境为准。
+
+### 5.5.4 评估顺序
+
+1. 先建立基准，不在没有数据时改配置。
+2. 检查索引是否被查询命中。
+3. 评估 WAL：
+
+   ```sql
+   PRAGMA journal_mode=WAL;
+   PRAGMA synchronous=NORMAL;
+   ```
+
+4. 评估单独读连接池：
+   - 写仍保持单连接；
+   - 读连接数量受控。
+5. 仍不达标时：
+   - 指标预聚合；
+   - 分区式表或定期归档；
+   - 避免在单次请求中加载全部历史。
+
+### 5.5.5 验收标准
+
+- 有可重复执行的基准命令。
+- 有基准结果记录到文档。
+- 任何连接策略变更都有并发测试与回滚方案。
+
+---
+
+## 6. P3：能力增强
+
+P3 每项都建议独立立项、独立迁移、独立 UI 和测试。
+
+---
+
+## 6.1 P3-1：加密迁移包
+
+### 6.1.1 目标
+
+支持导出一个包含敏感凭据的完整实例包，并在另一台 Fonu 上导入，用于换机、重装和灾备。
+
+### 6.1.2 与现有备份的区别
+
+| 能力 | 现有脱敏导出 | 加密迁移包 |
+| --- | --- | --- |
+| 保存设置与规则 | 部分 | 完整 |
+| 保存 DDNS / FRP 凭据 | 否 | 是，加密 |
+| 保存证书与私钥 | 否 | 是，加密 |
+| 保存会话 | 可选，不建议 | 默认不保存 |
+| 导入到其他实例 | 否 | 是 |
+| 需要口令 | 否 | 是 |
+
+### 6.1.3 包结构
+
+建议文件扩展名：
+
+```text
+.fonu-migrate
+```
+
+逻辑结构：
+
+```text
+manifest.json
+db/fonu.db
+certs/
+nginx/
+frp/
+settings/
+checksums.txt
+```
+
+不建议包含：
+
+- `logs/`
+- `backups/`
+- 正在运行的 socket / pid 文件
+- Agent 临时下载目录
+
+### 6.1.4 加密设计
+
+- KDF：Argon2id，使用随机 salt；
+- 对称加密：AES-256-GCM；
+- 文件按块加密，避免整包读入内存；
+- 每个块使用独立 nonce；
+- 包尾包含校验；
+- manifest 在解密后校验版本和 schema。
+
+如果选择引入成熟库，可评估 `age` 或其他流式加密库；否则复用现有 `golang.org/x/crypto/argon2`。
+
+### 6.1.5 导出流程
+
+1. 校验当前数据库可读。
+2. 使用 SQLite `VACUUM INTO` 生成一致快照。
+3. 收集证书、Nginx 配置、frp 配置。
+4. 生成 manifest 和 checksums。
+5. 打 tar。
+6. 流式加密到目标文件。
+7. 验证可解密并读取 manifest。
+8. 返回一次性下载。
+
+### 6.1.6 导入流程
+
+1. 只允许导入空实例，或要求显式“覆盖现有数据”。
+2. 上传后先写临时目录。
+3. 校验文件头、版本、schema、checksums。
+4. 解密到临时目录。
+5. 验证 SQLite 完整性：
+
+   ```sql
+   PRAGMA integrity_check;
+   ```
+
+6. 自动创建导入前备份。
+7. 原子替换数据目录关键文件。
+8. 要求重启 Fonu。
+
+### 6.1.7 接口与前端
+
+接口建议：
+
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| POST | `/api/migration/export` | 生成加密包 |
+| POST | `/api/migration/inspect` | 解密前只读元数据 |
+| POST | `/api/migration/import` | 导入 |
+
+前端放在设置页“数据”或“高级”中：
+
+- 口令与确认口令；
+- 导出按钮；
+- 上传与预检；
+- 显示版本、schema、文件数、创建时间；
+- 导入二次确认；
+- 结果提示与重启提醒。
+
+### 6.1.8 测试
+
+- 正确口令导出并导入；
+- 错误口令失败且不落盘；
+- 文件截断失败；
+- checksum 篡改失败；
+- 高版本 schema 拒绝；
+- 已存在数据默认拒绝覆盖；
+- 导入前自动备份生成。
+
+---
+
+## 6.2 P3-2：审计日志
+
+### 6.2.1 目标
+
+记录“谁、何时、从哪里、修改了什么、修改前是什么、修改后是什么”。
+
+### 6.2.2 数据表
+
+新增迁移：
+
+```sql
+CREATE TABLE audit_logs (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    actor_type TEXT NOT NULL,
+    actor_id TEXT NOT NULL,
+    actor_name TEXT NOT NULL,
+    source_ip TEXT NOT NULL,
+    action TEXT NOT NULL,
+    target_type TEXT NOT NULL,
+    target_id TEXT NOT NULL,
+    summary TEXT NOT NULL,
+    before_json TEXT,
+    after_json TEXT,
+    created_at TEXT NOT NULL
+);
+```
+
+建议索引：
+
+```sql
+CREATE INDEX idx_audit_logs_created_at ON audit_logs(created_at);
+CREATE INDEX idx_audit_logs_target ON audit_logs(target_type, target_id, created_at);
+```
+
+### 6.2.3 记录范围
+
+必须审计：
+
+- 反代规则创建、修改、删除、排序；
+- Nginx 配置保存与回滚；
+- DDNS 创建、修改、删除、凭证更新；
+- 证书申请、导入、续期、删除；
+- FRP 服务端与规则创建、修改、删除；
+- Agent 安装、升级、卸载；
+- frps 配置下发与启停；
+- 设置修改；
+- API Token 创建与撤销；
+- 管理员改密、2FA 变更；
+- 备份恢复与迁移导入。
+
+不记录：
+
+- 已脱敏字段的真实值；
+- 密码、Token、私钥明文；
+- 每次 GET 和无副作用的轮询。
+
+### 6.2.4 实现方式
+
+新增：
+
+```text
+internal/audit
+```
+
+建议接口：
+
+```go
+type Entry struct {
+    ActorType string
+    ActorID   string
+    ActorName string
+    SourceIP  string
+    Action    string
+    TargetType string
+    TargetID  string
+    Summary   string
+    Before    any
+    After     any
+}
+
+func (s *Service) Record(ctx context.Context, entry Entry) error
+```
+
+在业务成功写入后记录，不用全局中间件猜测副作用。
+
+### 6.2.5 前端
+
+新增审计页或在日志中心增加“审计”页签：
+
+- 时间范围；
+- 操作者；
+- 动作类型；
+- 目标；
+- 来源 IP；
+- 详情弹窗显示脱敏前后差异。
+
+### 6.2.6 保留策略
+
+- 默认保留 180 天；
+- 设置页可配置 30/90/180/365/永久；
+- 清理任务加入 scheduler。
+
+### 6.2.7 测试
+
+- 每个写入口成功时记录；
+- 失败操作不误记成功；
+- 敏感字段被掩码；
+- API Token 与会话都能识别 actor；
+- 分页、筛选和保留策略。
+
+---
+
+## 6.3 P3-3：2FA / TOTP 与登录设备管理
+
+### 6.3.1 数据模型
+
+`admins` 扩展：
+
+```text
+totp_secret_enc
+totp_enabled
+totp_confirmed_at
+recovery_codes_json
+```
+
+`sessions` 扩展：
+
+```text
+user_agent
+source_ip
+last_seen_at
+label
+created_at
+```
+
+新增登录挑战表：
+
+```sql
+CREATE TABLE login_challenges (
+    id TEXT PRIMARY KEY,
+    admin_id INTEGER NOT NULL,
+    expires_at TEXT NOT NULL,
+    attempts INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL
+);
+```
+
+### 6.3.2 登录流程
+
+```text
+用户名密码校验
+  → 未开 2FA：直接创建 session
+  → 已开 2FA：返回 challenge
+  → 用户提交 TOTP 或恢复码
+  → 校验成功创建 session
+```
+
+### 6.3.3 接口
+
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| GET | `/api/auth/2fa/status` | 当前账号 2FA 状态 |
+| POST | `/api/auth/2fa/setup` | 生成 secret 与 otpauth URI |
+| POST | `/api/auth/2fa/enable` | 校验首个 TOTP 并启用 |
+| POST | `/api/auth/2fa/disable` | 密码 + TOTP 二次确认后关闭 |
+| POST | `/api/auth/2fa/verify` | 登录挑战校验 |
+| POST | `/api/auth/2fa/recovery` | 使用恢复码登录 |
+| GET | `/api/settings/sessions` | 登录设备列表 |
+| DELETE | `/api/settings/sessions/{id}` | 踢下线 |
+
+### 6.3.4 安全要求
+
+- TOTP secret 使用现有 secret box 加密；
+- 恢复码只显示一次，库中存哈希；
+- challenge 短有效期，5 分钟；
+- 最大尝试次数，超过后作废；
+- TOTP 窗口限制 ±1 step；
+- 记录最近成功 step，拒绝重放；
+- 修改 2FA 需登录会话，不允许 API Token；
+- 禁用 2FA 需密码与 TOTP 双确认。
+
+### 6.3.5 前端
+
+设置页“安全”增加：
+
+- 2FA 状态卡；
+- 二维码绑定；
+- 恢复码一次性展示；
+- 关闭确认；
+- 登录设备列表；
+- “退出其他设备”和单设备撤销。
+
+### 6.3.6 测试
+
+- TOTP 正确 / 错误 / 过期；
+- 恢复码一次性；
+- 挑战过期与尝试上限；
+- 禁用 2FA 需要双确认；
+- 会话列表与撤销；
+- API Token 不能管理 2FA 和会话。
+
+---
+
+## 6.4 P3-4：SMART 磁盘健康与 UPS 状态
+
+### 6.4.1 目标
+
+在仪表盘增加 NAS 硬件健康：
+
+- 磁盘 SMART 温度、通电时长、重分配扇区、待处理扇区、总体健康；
+- UPS 电量、剩余时间、市电状态。
+
+### 6.4.2 后端设计
+
+新增：
+
+```text
+internal/hardware
+```
+
+接口：
+
+```go
+type DiskHealth struct {
+    Device           string
+    Model            string
+    Serial           string
+    Health           string
+    TemperatureC     int
+    PowerOnHours     uint64
+    Reallocated      uint64
+    PendingSectors   uint64
+    Uncorrectable    uint64
+    Available        bool
+    Error            string
+}
+
+type UPSStatus struct {
+    Name             string
+    Online           bool
+    BatteryChargePct int
+    RuntimeSeconds   int
+    LoadPct          int
+    Available        bool
+    Error            string
+}
+```
+
+### 6.4.3 SMART 采集
+
+1. 从 `/sys/block` 枚举物理块设备。
+2. 排除：
+   - loop；
+   - ram；
+   - dm；
+   - md 虚拟设备。
+3. 检测 `smartctl` 是否存在。
+4. 固定 argv 执行：
+
+   ```bash
+   smartctl -H -A -j /dev/sdX
+   ```
+
+5. 解析 JSON。
+6. 结果缓存 5 分钟，避免频繁唤醒磁盘。
+7. 无权限时返回 `Available=false` 和明确错误，不影响仪表盘。
+
+### 6.4.4 UPS 采集
+
+优先 NUT：
+
+```bash
+upsc <ups>@localhost
+```
+
+解析：
+
+- `ups.status`
+- `battery.charge`
+- `battery.runtime`
+- `ups.load`
+
+如果没有 NUT，尝试只读 `/sys/class/power_supply`。
+
+### 6.4.5 接口与告警
+
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| GET | `/api/hardware/disks` | 磁盘健康 |
+| GET | `/api/hardware/ups` | UPS 状态 |
+| GET | `/api/status` | 合并一条硬件摘要 |
+
+告警事件：
+
+- SMART 健康非 PASSED；
+- 温度超过阈值；
+- 重分配 / 待处理扇区增加；
+- UPS 切换到电池；
+- 电量低于阈值；
+- 剩余时间低于阈值。
+
+### 6.4.6 前端
+
+仪表盘新增“硬件健康”卡：
+
+- 磁盘数量；
+- 异常磁盘数；
+- 最高温度；
+- UPS 电量；
+- 剩余时间；
+- 点击展开详情。
+
+### 6.4.7 测试
+
+- smartctl JSON fixture；
+- 无 smartctl；
+- 权限不足；
+- 磁盘休眠或读取失败；
+- NUT 存在 / 不存在；
+- 多个 UPS；
+- 阈值告警与恢复。
+
+---
+
+## 6.5 P3-5：Prometheus `/metrics` 导出
+
+### 6.5.1 目标
+
+让 Grafana、VictoriaMetrics、HomeAssistant 等系统可以直接抓取 Fonu 指标。
+
+### 6.5.2 鉴权策略
+
+推荐：
+
+1. 新增设置项 `prometheus_enabled`，默认关闭。
+2. 新增设置项 `prometheus_token`：
+   - 只显示一次；
+   - 库中保存哈希。
+3. 支持：
+
+   ```http
+   Authorization: Bearer <prometheus_token>
+   ```
+
+4. 也允许使用已有 `read` API Token。
+5. 未启用时返回 404，避免暴露端点存在。
+
+### 6.5.3 指标设计
+
+```text
+fonu_build_info{version,agent_version}
+fonu_host_cpu_percent
+fonu_host_memory_bytes{state="used|total"}
+fonu_host_disk_bytes{state="used|total"}
+fonu_proxy_traffic_bytes_total{rule_id,name,direction}
+fonu_proxy_connections{rule_id,name}
+fonu_route_up{server_id,domain}
+fonu_route_uptime_ratio{server_id,domain,window}
+fonu_frp_server_up{server_id,name}
+fonu_frp_server_latency_ms{server_id,name}
+fonu_certificate_days_left{domain}
+fonu_notify_events_total{event,result}
+```
+
+### 6.5.4 采集策略
+
+- 使用 `prometheus/client_golang`；
+- 抓取时读取内存缓存或当前快照；
+- 数据库查询设置 2 秒超时；
+- 不因一个数据源失败让整个抓取失败；
+- 控制 label 数量，避免规则名称无限增长；
+- 不暴露凭据、路径、内网上游。
+
+### 6.5.5 前端
+
+设置页增加：
+
+- 开关；
+- Token 创建与复制；
+- 抓取地址示例；
+- 当前状态。
+
+### 6.5.6 测试
+
+- 未启用 404；
+- 无 Token 401；
+- 正确 Token 200；
+- 输出格式可被 Prometheus parser 解析；
+- 标签不包含敏感路径；
+- 数据源失败时仍能导出部分指标。
+
+---
+
+## 6.6 P3-6：状态页事故记录与服务入口聚合
+
+### 6.6.1 状态页事故记录
+
+现有 `route_health_events` 已经记录状态变化，可用于推导事故。
+
+新增：
+
+- 当前未恢复事故；
+- 最近 24 小时 / 7 天事故列表；
+- 开始时间、结束时间、持续时长、原因；
+- 每条规则的可用率。
+
+接口：
+
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| GET | `/api/status-page` | 增加 active incidents |
+| GET | `/api/status-page/incidents` | 查询事故窗口 |
+
+公开状态页仍然只显示：
+
+- 域名；
+- 状态；
+- 可用率；
+- 事故时间；
+- 不含内网地址、端口、证书路径和上游地址。
+
+### 6.6.2 服务入口聚合
+
+目标：在仪表盘把启用中的服务聚合为可点击入口。
+
+数据源：
+
+- 本机 `proxy_rules` 与 `proxy_hosts`；
+- 公网 FRP 规则与域名；
+- 健康状态；
+- 证书状态。
+
+接口建议：
+
+```http
+GET /api/services
+```
+
+返回：
+
+```json
+{
+  "items": [
+    {
+      "name": "示例服务",
+      "domain": "app.example.com",
+      "source": "proxy",
+      "scheme": "https",
+      "health": "up",
+      "cert_days_left": 72
+    }
+  ]
+}
+```
+
+前端：
+
+- 卡片或紧凑列表；
+- 按来源筛选；
+- 健康点；
+- 点击打开新窗口；
+- 复制域名；
+- 无启用规则时显示空态。
+
+### 6.6.3 性能要求
+
+- 服务入口读取缓存，不逐条探测；
+- 健康结果复用 monitor 最近一轮；
+- 100 条规则时接口目标小于 100ms；
+- 公开状态页不能查询敏感表。
+
+### 6.6.4 测试
+
+- 事故从状态变化推导正确；
+- 未恢复事故持续增长；
+- unknown 不计入 down；
+- 服务入口不含重复域名；
+- 无健康数据时显示 unknown；
+- 公开状态页不泄露内网信息。
+
+---
+
+## 7. 跨模块测试矩阵
+
+| 场景 | 本地 Go | 前端 | Docker | fnOS host | VPS Debian | 宝塔 Nginx |
+| --- | --- | --- | --- | --- | --- | --- |
+| P0 修复 | 必须 | 必须 | 可选 | 建议 | 可选 | 可选 |
+| Agent Token / 监听 | 必须 | 建议 | 必须 | 可选 | 必须 | 必须 |
+| Nginx 模板收敛 | 必须 | 必须 | 必须 | 必须 | 必须 | 必须 |
+| FRP / Agent 拆分 | 必须 | 可选 | 建议 | 可选 | 必须 | 必须 |
+| 前端拆分 | 可选 | 必须 | 建议 | 必须 | 可选 | 可选 |
+| SQLite 基准 | 必须 | 可选 | 必须 | 必须 | 可选 | 可选 |
+| 迁移包 | 必须 | 必须 | 可选 | 必须 | 可选 | 可选 |
+| 2FA | 必须 | 必须 | 可选 | 建议 | 可选 | 可选 |
+| SMART / UPS | 必须 | 必须 | 建议 | 必须 | 可选 | 可选 |
+| Prometheus | 必须 | 必须 | 必须 | 建议 | 可选 | 可选 |
+
+### 7.1 平台注意事项
+
+- Windows 仅用于开发，不作为生产验证依据。
+- fnOS host 模式必须验证 80/443 被系统 Nginx 占用时的行为。
+- Debian / Ubuntu 与宝塔环境的 Nginx 路径不同，Agent 必须都能探测。
+- 旧 Agent 必须与新控制端兼容。
+- 新 Agent 必须兼容旧控制端的基础状态接口。
+
+---
+
+## 8. 发布与回滚策略
+
+### 8.1 版本建议
+
+| 里程碑 | 版本类型 | 内容 |
+| --- | --- | --- |
+| M1 | patch | P0 修复与安全边界 |
+| M2 | minor | P1 重构与测试基线 |
+| M3 | patch/minor | P2 工程收口 |
+| M4 | minor | 迁移包、审计、2FA |
+| M5 | minor | SMART / UPS、Prometheus、状态页增强 |
+
+最终版本号仍以实际兼容性判断为准。
+
+### 8.2 Agent 版本
+
+以下改动必须递增 `AgentVersion`：
+
+- 常量时间 Token；
+- 监听策略；
+- 限流状态错误处理；
+- Nginx 模板变化；
+- vhost 版本、证书、frps 与日志接口变化。
+
+发布时：
+
+1. 更新 `AgentVersion`；
+2. 重编 amd64 / arm64；
+3. 替换 `internal/frp/agentbin`；
+4. 更新 CHANGELOG；
+5. 在 VPS 上升级 Agent 后验证。
+
+### 8.3 数据库
+
+每个 P3 功能各自新增迁移：
+
+- 迁移编号按现有文件顺序递增；
+- 不修改已发布迁移；
+- 迁移前自动备份；
+- 升级失败时恢复数据库。
+
+### 8.4 回滚
+
+| 改动 | 回滚方式 |
+| --- | --- |
+| 前端 P0 修复 | 退回旧前端构建 |
+| 初始密码日志策略 | 恢复旧输出代码，不涉及数据 |
+| Agent 安全策略 | 回滚 Agent 二进制，保留旧配置 |
+| Nginx 模板 | 使用已有配置版本回滚 |
+| 文件拆分 | 纯代码回滚，不影响运行数据 |
+| 数据库迁移 | 使用升级前备份恢复 |
+| 迁移包导入 | 使用自动创建的导入前备份恢复 |
+
+---
+
+## 9. 实施检查清单
+
+### 9.1 每个 P0 任务
+
+- [ ] 复现问题；
+- [ ] 写失败测试；
+- [ ] 最小修复；
+- [ ] 验证正常路径；
+- [ ] 验证失败路径；
+- [ ] 更新文档；
+- [ ] 记录是否需要 Agent 升级。
+
+### 9.2 每个 P1 重构
+
+- [ ] 先确认当前测试全绿；
+- [ ] 只做文件移动或纯函数抽取；
+- [ ] 保持包外 API 不变；
+- [ ] 每步跑全量 Go 测试；
+- [ ] 前端改动跑 typecheck、test、build；
+- [ ] 使用截图验证关键页面；
+- [ ] 不混入业务功能。
+
+### 9.3 每个 P2 清理
+
+- [ ] 有引用证明；
+- [ ] diff 可审查；
+- [ ] 不含未确认删除；
+- [ ] CI 卡口通过；
+- [ ] 视觉和主题无回归。
+
+### 9.4 每个 P3 功能
+
+- [ ] 独立迁移；
+- [ ] 独立接口；
+- [ ] 独立 UI；
+- [ ] 安全评审；
+- [ ] 降级路径；
+- [ ] 文档和示例；
+- [ ] 性能与并发测试；
+- [ ] 备份和回滚验证。
+
+---
+
+## 10. 需要用户提前决策的事项
+
+1. **Agent 监听默认值**：
+   - 是否接受新安装默认 `127.0.0.1:7700`；
+   - 是否接受远程模式必须显式配置 HTTPS 或 `--insecure-allow-http`。
+2. **迁移包加密实现**：
+   - 使用自研 Argon2id + AES-GCM 分块格式，还是引入成熟加密库；
+   - 导入是否只允许空实例，还是也支持显式覆盖。
+3. **2FA 依赖**：
+   - 是否允许引入 TOTP / QR 相关第三方库；
+   - 恢复码数量与格式。
+4. **Prometheus 鉴权**：
+   - 使用独立 Token，还是允许现有 read API Token；
+   - 端点使用 `/metrics` 还是 `/api/metrics/prometheus`。
+5. **审计保留期**：
+   - 默认 180 天是否合适；
+   - 是否允许永久保留。
+6. **SMART 权限边界**：
+   - Fonu 容器是否默认具有访问宿主磁盘设备的权限；
+   - 只读失败时是否接受只显示“不可用”。
+
+---
+
+## 11. 最终建议
+
+最合理的实施方式不是按 P0→P3 一次性做完，而是先完成 M1，把明确缺陷和安全性问题清掉；随后用 M2 的测试基线保护 FRP / Agent 重构；等核心模块稳定后，再做前端拆分和工程清理；最后按产品价值逐项推进 P3。
+
+如果只能先做三项，建议顺序是：
+
+1. **P0-1 + P0-2 + P0-4**：直接修复用户可见缺陷、日志泄密和配置丢失风险；
+2. **P1-4 + P1-2**：先建立保护网，再拆 FRP / Agent 巨型文件；
+3. **P1-1**：收敛 Nginx 模板，消除本机与公网两套安全逻辑漂移的根因。
+
+这样可以在不破坏现有部署的前提下，逐步把 Fonu 从“功能完整但复杂度集中”推进到“模块清晰、测试可靠、升级可控”的状态。
diff --git a/docs/project-analysis-2026-09-27.md b/docs/project-analysis-2026-09-27.md
new file mode 100644
index 0000000..0a5d173
--- /dev/null
+++ b/docs/project-analysis-2026-09-27.md
@@ -0,0 +1,983 @@
+# Fonu 项目详细分析（v1.2.19）
+
+> 分析日期：2026-09-27  
+> 分析对象：`F:\Fonu-main\Fonu-1.0.2`  
+> 代码版本：`VERSION = 1.2.19`，前端 `package.json = 1.2.19`，内置 Agent `0.12.7`  
+> 分析方式：源码静态阅读、目录与依赖统计、迁移与路由核对、构建级验证  
+> 验证结果：`go test ./... -count=1`、`go vet ./...`、`npm run typecheck`、`npm test` 均通过
+
+---
+
+## 一、结论摘要
+
+Fonu 是面向飞牛 fnOS 和家庭 NAS 场景的「公网访问管理面板」。它把四类原本分散的运维能力收敛到一个 Go 单体和 Vue 管理后台中：
+
+1. 本机 Nginx 反向代理与配置版本管理；
+2. 多家 DNS 服务商的 DDNS 自动同步；
+3. ACME 证书申请、续期、导入与下载；
+4. 基于 FRP 的内网穿透，以及部署在公网 VPS 上的 `fonu-agent` 远程管理。
+
+项目当前形态不是单纯 CRUD 面板，而是已经形成「本地控制面 + 公网 Agent + 定时任务 + SQLite 状态库 + Nginx 配置生成器」的完整运维系统。
+
+主要优点：
+
+- **模块边界较清楚**：`internal` 下按 `proxy`、`nginx`、`ddns`、`acme`、`frp`、`agent`、`monitor`、`backup` 等领域拆分，应用装配集中在 `internal/app/app.go`。
+- **交付链路完整**：同一套源码可构建 Docker 镜像、Linux amd64/arm64 原生安装包，并内嵌双架构 `fonu-agent`。
+- **关键配置具备回滚能力**：本机 Nginx 主配置、规则自定义配置，以及公网 Agent 上的 vhost 都有版本列表、差异和回滚入口。
+- **自动化程度较高**：DDNS、证书续期、中国 IP 段更新、健康巡检、指标采样、自动备份均由调度器统一驱动。
+- **测试基础设施已建立**：后端 90 个 Go 测试文件；前端已有 Vitest、TypeScript 严格模式与 CI 验证流程。
+
+需要重点关注：
+
+- **FRP 是系统复杂度中心**：`internal/frp` 约 6049 行，`internal/agent` 约 2079 行，二者共同承担 VPS 配置、进程、Nginx、证书、frps、诊断、版本与漂移检测，修改风险高于其他模块。
+- **前端巨型组件明显**：`ProxyView.vue` 约 3150 行，`SettingsView.vue` 约 2144 行，`AgentView.vue` 约 1807 行，维护和样式隔离成本较高。
+- **仍存在历史遗留接口引用**：前端保留 `/api/frp` 旧方法，`DdnsView.vue` 仍调用它，但后端当前只注册 `/api/frpmulti/*`；该调用落入 `catch`，会造成 DDNS 页的 FRP 提示状态始终为关闭。
+- **初始管理员密码会进入系统日志**：`auth.EnsureDefaultAdmin` 将初始密码写入应用日志，日志中心的系统日志又会读取该文件，安全边界需要收紧。
+- **仓库工作区有未提交改动**：当前有归档目录删除、内置 Agent 二进制更新、品牌图片更新等本地改动；分析时没有修改或回退这些内容。
+
+---
+
+## 二、仓库定位与目录边界
+
+外层目录 `F:\Fonu-main` 不是项目源码仓库，而是工作区容器：
+
+```text
+F:\Fonu-main
+├─ .breezell/                 工作区辅助目录
+├─ .gocache-agent/            Agent 构建缓存
+├─ docs/                      外层临时文档
+├─ Fonu-1.0.2/                真正的 Git 仓库与源码根目录
+├─ agent-tsc.log
+├─ fonu-image-build4.log
+└─ frps-m1-tsc.log
+```
+
+真正的 Git 仓库位于 `F:\Fonu-main\Fonu-1.0.2`：
+
+- 当前分支：`main`
+- 远端：`origin/main`
+- 最近提交：`70b891c feat(scripts): 新增 upgrade-hub.sh，仅编排文件的部署可一条命令升级`
+- 当前未提交内容：
+  - 删除 `internal/frp-1.0.2/*`；
+  - 删除 `web/src/views/FrpView-1.0.2.vue`；
+  - 修改 `internal/frp/agentbin/fonu-agent-linux-amd64`；
+  - 修改 `internal/frp/agentbin/fonu-agent-linux-arm64`；
+  - 修改 `web/public/favicon.png`、`web/src/assets/brand/logo.png`；
+  - 新增 `web/public/111favicon.png`、`web/src/assets/brand/logo00.png`。
+
+项目主体目录：
+
+| 目录 | 作用 |
+| --- | --- |
+| `cmd/fonu` | 本地控制面主程序入口，嵌入前端静态资源 |
+| `cmd/fonu-agent` | 公网 VPS Agent 入口 |
+| `internal` | 全部业务实现，共 29 个领域包 |
+| `migrations` | SQLite 迁移，共 27 个 SQL 文件 |
+| `web` | Vue 3 + Vite 管理后台 |
+| `deploy` | Nginx MIME 类型等部署资源 |
+| `scripts` | 原生安装、升级、Agent 安装和 Linux 打包脚本 |
+| `docs` | 设计、审查、部署与 FRP 文档 |
+| `.github/workflows` | CI、Docker 发布、GitHub Release |
+
+---
+
+## 三、总体架构
+
+```mermaid
+flowchart LR
+    Browser[浏览器管理后台] -->|HTTP :6893 / Cookie / Bearer Token| App[fonu 控制面]
+    Public[公网访客] -->|HTTP/HTTPS| Nginx[本机 Nginx]
+    Nginx -->|反向代理| NAS[NAS 内网服务]
+
+    App --> DB[(SQLite /data/fonu.db)]
+    App --> FS[数据目录 /data]
+    App --> NginxCtl[Nginx 配置生成与重载]
+    App --> DDNS[Cloudflare / DNSPod / 阿里云 / 腾讯云 / 火山引擎]
+    App --> ACME[ACME CA]
+    App --> Scheduler[后台调度器]
+
+    App -->|frpc.toml / 进程管理| FRPC[本机 frpc]
+    FRPC -->|隧道| FRPS[公网 VPS frps]
+    FRPS -->|vhost| AgentNginx[VPS Nginx]
+    AgentNginx -->|隧道回源| Nginx
+
+    App -->|Bearer Token API :7700| Agent[fonu-agent]
+    Agent --> AgentNginx
+    Agent --> FRPS
+    Agent --> CertStore[VPS 证书目录]
+```
+
+运行角色：
+
+| 角色 | 运行位置 | 职责 |
+| --- | --- | --- |
+| `fonu` | NAS / Docker / 原生 Linux | 管理后台、本机 Nginx、DDNS、证书、frpc、调度器、数据持久化 |
+| `fonu-agent` | 公网 VPS | 管理 VPS 上的 Nginx vhost、证书副本、frps 进程与配置，并提供诊断只读接口 |
+| Nginx | NAS 与 VPS 两端 | NAS 侧负责反代与流量入口；VPS 侧负责公网反代和 frps vhost 回源 |
+| frpc / frps | NAS / VPS | 在无公网 IP 时建立 TCP、HTTP、HTTPS 等隧道 |
+| SQLite | NAS 数据目录 | 保存账号、会话、代理规则、DDNS、证书、FRP、指标、健康、备份元数据等 |
+
+---
+
+## 四、技术栈与构建交付
+
+### 4.1 后端
+
+`go.mod` 声明 Go 1.23，模块路径为 `github.com/fonu/fonu`。本次验证环境使用 Go 1.26.2，可正常构建与测试。
+
+关键依赖：
+
+| 能力 | 依赖 |
+| --- | --- |
+| HTTP 服务 | Go 标准库 `net/http` 与 `http.ServeMux` |
+| SQLite | `modernc.org/sqlite`，纯 Go，不依赖 CGO |
+| ACME | `github.com/go-acme/lego/v4` |
+| DNSPod | `github.com/nrdcg/dnspod-go` |
+| 腾讯云 | `tencentcloud-sdk-go` |
+| 火山引擎 | `volcengine-go-sdk` |
+| SSH | `golang.org/x/crypto/ssh` |
+| 密码哈希 | `golang.org/x/crypto/bcrypt` |
+| 日志轮转 | `gopkg.in/natefinch/lumberjack.v2` |
+
+后端有两个入口：
+
+- `cmd/fonu/main.go`：加载配置、解析迁移目录、嵌入 `web/dist`、启动 `app.New`、监听退出信号。
+- `cmd/fonu-agent/main.go`：解析监听地址、Token、Nginx 目录、证书目录、frps 路径，启动 Agent HTTP 服务。
+
+### 4.2 前端
+
+前端使用 Vue 3.5、TypeScript 5.7、Vite 6：
+
+| 能力 | 依赖 |
+| --- | --- |
+| UI 组件 | Naive UI |
+| 路由 | Vue Router |
+| 图表 | ECharts + vue-echarts |
+| 配置编辑器 | CodeMirror 6 |
+| 拖拽排序 | SortableJS |
+| 图标 | `@vicons/ionicons5` |
+| 测试 | Vitest |
+
+`web/src` 共 52 个 TypeScript / Vue 源文件。前端测试目前有 2 个 spec、13 条测试，主要集中在格式化与状态映射纯函数。
+
+### 4.3 Docker 与原生安装
+
+项目提供三种 Compose：
+
+| 文件 | 场景 | 网络 |
+| --- | --- | --- |
+| `docker-compose.yml` | 普通 Docker、本地源码构建 | bridge，映射 6893/18080/9443 |
+| `docker-compose.host.yml` | 飞牛 fnOS 等已占用 80/443 的环境 | host 网络，默认反代端口 18080/9443 |
+| `docker-compose.hub.yml` | 干净机器只保留一个编排文件 | BuildKit 直接从 Git 仓库拉源码构建 |
+
+Dockerfile 的主要流程：
+
+1. 从根目录 `VERSION` 读取版本；
+2. 构建前端；
+3. 交叉编译 Linux amd64 / arm64 `fonu-agent`；
+4. 将前端 `dist` 复制到 `cmd/fonu/web/dist` 供 `go:embed`；
+5. 编译 `fonu` 主程序；
+6. 运行时镜像安装 Nginx、CA 证书、tzdata；
+7. 默认监听 6893，暴露 80/443，数据目录为 `/data`。
+
+注意：当前 Dockerfile 不预装 `frpc`，需要用户在「应用配置」中按需下载。旧版 README 或部署文档中若仍表述为“镜像内置 frpc”，应按当前实现校正。
+
+### 4.4 版本一致性
+
+当前版本事实：
+
+| 位置 | 值 |
+| --- | --- |
+| `VERSION` | `1.2.19` |
+| `web/package.json` | `1.2.19` |
+| `AgentVersion` | `0.12.7` |
+| `internal/version.Version` | 构建时通过 `-ldflags` 注入，默认 `dev` |
+
+前端构建时优先读取 `VITE_APP_VERSION`，否则回落到 `package.json`。Dockerfile 将 `VERSION` 注入前端和后端。
+
+---
+
+## 五、后端模块分析
+
+### 5.1 规模概览
+
+后端共有 235 个 `.go` 文件，其中 90 个是 `_test.go`。按非测试源码粗略统计，主要模块规模如下：
+
+| 包 | 文件数 | 约行数 | 职责 |
+| --- | ---: | ---: | --- |
+| `frp` | 23 | 6049 | FRP 多服务端、frpc 运行、Agent 调用、诊断、健康、漂移、版本 |
+| `api` | 22 | 3241 | HTTP 路由、处理器、中间件、响应封装 |
+| `ddns` | 14 | 2379 | 多服务商 DDNS、记录同步、凭证、Zone 解析 |
+| `nginx` | 23 | 2186 | Nginx 配置生成、校验、启动、重载、版本与回滚 |
+| `agent` | 4 | 2079 | 公网 VPS Agent 的全部接口与配置写入 |
+| `notify` | 7 | 1418 | 通知配置、加密存储、邮件、Webhook、Telegram 与国内 IM |
+| `acme` | 8 | 1370 | ACME 申请、续期、导入、导出、任务日志 |
+| `proxy` | 3 | 1015 | 反代规则模型、SQLite Store 与端口冲突校验 |
+| `service` | 3 | 595 | 反代与 Nginx 配置的业务服务层 |
+| `monitor` | 1 | 559 | 资源、隧道、服务端、Agent、配置漂移巡检 |
+| `logstore` | 4 | 685 | 系统日志、访问日志、错误日志读取与显示转换 |
+| `traffic` | 3 | 421 | Nginx access log 跟踪、流量聚合、在线连接 |
+| `backup` | 3 | 401 | 导出、恢复、校验、自动备份与保留策略 |
+| `certificate` | 2 | 353 | 证书元数据 Store 与导入 |
+| `auth` | 2 | 334 | 管理员、会话、API Token 验证 |
+| `chinacidr` | 1 | 301 | 中国 IP 段下载、生成与 Nginx 联动 |
+| `metrics` | 1 | 231 | 指标历史写入、查询与分桶 |
+| `config` | 1 | 201 | 环境变量、数据目录、会话密钥 |
+| `settings` | 1 | 193 | 设置项读写、默认值与类型转换 |
+| `fsutil` | 1 | 164 | 原子写、备份、版本列表与回滚基础 |
+
+### 5.2 应用装配：`internal/app/app.go`
+
+`app.New` 是理解整个系统的入口，按顺序完成：
+
+1. 创建日志目录与 JSON 日志；
+2. 创建数据、Nginx、日志、证书、FRP 目录；
+3. 解析或自动生成会话密钥；
+4. 打开 SQLite 并执行迁移；
+5. 创建 AES-GCM 凭据加密盒；
+6. 初始化管理员账号；
+7. 创建 proxy、settings、ddns、certificate、nginx 等 Store / Service；
+8. 创建 FRP 多服务端服务；
+9. 创建 HTTP 路由；
+10. 创建调度器与流量采集器；
+11. 启动 DDNS、ACME、中国 IP、巡检、自动备份任务；
+12. 初始化 Nginx 配置并恢复 frpc 运行状态；
+13. 启动 HTTP 服务，退出时关闭 Nginx、frpc 和数据库。
+
+这种集中装配方式让依赖关系清晰，但也使 `app.go` 成为高耦合入口。新增模块时应继续通过构造参数或小型接口注入，避免在 `app.New` 中堆积具体职责。
+
+### 5.3 配置与数据目录：`internal/config`
+
+关键环境变量：
+
+| 变量 | 默认值 | 说明 |
+| --- | --- | --- |
+| `FONU_LISTEN` | `:6893` | 管理后台监听地址 |
+| `FONU_DATA_DIR` | `/data` 或当前目录 `.data` | 数据根目录 |
+| `FONU_SESSION_SECRET` | 空 | 会话签名与凭据加密密钥；空时自动生成 |
+| `FONU_NGINX_BIN` | `nginx` | Nginx 可执行文件 |
+| `FONU_NGINX_PID` | `<DataDir>/nginx/nginx.pid` | Nginx PID |
+| `FONU_NGINX_MIME_TYPES` | `/etc/nginx/mime.types` 或仓库资源 | MIME 类型文件 |
+| `FONU_NGINX_HTTP_PORT` | `80` | 新建 HTTP 反代默认端口 |
+| `FONU_NGINX_HTTPS_PORT` | `443` | 新建 HTTPS 反代默认端口 |
+| `FONU_FRPC_BIN` | `frpc` | frpc 可执行文件 |
+| `FONU_FRPC_PID` | `<DataDir>/frp/frpc.pid` | frpc PID 文件 |
+
+会话密钥策略值得肯定：
+
+- 显式配置时优先使用；
+- 未配置时生成 32 字节随机值；
+- 持久化为 `<DataDir>/session_secret`，权限 0600；
+- 使用临时文件加改名写入，避免半文件；
+- 已经使用历史默认值时只提示，不自动替换，避免历史密文全部无法解密。
+
+数据目录典型结构：
+
+```text
+<DataDir>/
+├─ fonu.db
+├─ session_secret
+├─ ssh_known_hosts
+├─ nginx/
+│  ├─ nginx.conf
+│  ├─ rules/
+│  ├─ custom/
+│  ├─ backups/
+│  ├─ errors/
+│  └─ china_cidr.conf
+├─ certs/
+├─ frp/
+│  ├─ frpc.toml
+│  └─ frpc.pid
+├─ logs/
+│  ├─ app.log
+│  ├─ access.log
+│  ├─ error.log
+│  └─ frpc.log
+└─ backups/
+```
+
+### 5.4 数据库：`internal/db`
+
+SQLite 初始化参数：
+
+- `foreign_keys(1)`：启用外键；
+- `busy_timeout(5000)`：锁等待 5 秒；
+- `SetMaxOpenConns(1)`：单连接串行访问。
+
+单连接是保守且适合 NAS 单机场景的选择，能避免多连接写冲突，但所有 API、调度任务和日志查询都共享一个数据库连接。当历史指标、健康事件和流量查询增大时，响应延迟可能互相影响。
+
+迁移系统特点：
+
+- 按文件名前缀数字排序；
+- 每个迁移在独立事务中执行；
+- 成功后写入 `schema_migrations`；
+- 已应用版本跳过；
+- 迁移文件不嵌入二进制，运行时通过 `ResolveMigrationsDir` 在多个候选路径查找。
+
+### 5.5 认证与凭据
+
+认证能力分三类：
+
+1. 管理员账号：bcrypt 哈希；
+2. 浏览器会话：32 字节随机 Token，数据库保存，默认 7 天；
+3. API Token：随机明文只返回一次，数据库保存 SHA-256，支持 `read` / `write` 范围。
+
+登录保护：
+
+- 同一 IP 在 5 分钟内失败 5 次后返回 429；
+- 登录失败会进入通知统计；
+- 修改密码后删除该账号的其他会话，保留当前会话；
+- Cookie 使用 `HttpOnly`、`SameSite=Lax`，并根据直连 TLS 或 `X-Forwarded-Proto` 设置 `Secure`。
+
+凭据加密：
+
+- 使用会话密钥经 SHA-256 派生 AES-256-GCM；
+- 加密 DDNS、FRP、通知、SSH、Dashboard 和 OIDC 等敏感字段；
+- 部分凭据 API 只返回 `has_token` / `has_password` 等状态，不回传明文。
+
+---
+
+## 六、数据库模型
+
+### 6.1 表清单
+
+| 表 | 迁移 | 作用 |
+| --- | --- | --- |
+| `schema_migrations` | 001 | 迁移版本 |
+| `admins` | 001 | 管理员账号 |
+| `sessions` | 001 | 浏览器会话 |
+| `api_tokens` | 025 | API 脚本令牌 |
+| `proxy_rules` | 001 / 006 / 010-014 | 本机反向代理规则 |
+| `proxy_hosts` | 006 / 010 | 规则域名与监听端口 |
+| `proxy_custom_endpoints` | 024 | 自定义 Nginx 规则解析出的域名端口占用 |
+| `proxy_traffic` | 009 | 规则累计流量 |
+| `ddns_configs` | 002-008 / 022 | DDNS 任务、记录、凭证、自定义 IP |
+| `certificates` | 002 / 004 / 005 | 证书元数据、CA、多域名 |
+| `settings` | 001 | 键值设置 |
+| `frp_servers` | 015-016 / 020 / 023 | FRP 服务端、认证、Dashboard、Agent、SSH |
+| `frp_proxies` | 015 / 018 / 021 | FRP 穿透规则与扩展选项 |
+| `frp_runtime_status` | 015 / 019 | frpc 期望状态、进程状态、连接状态 |
+| `frp_server_diagnostics` | 017 | 服务端延迟与可用性采样 |
+| `route_health_events` | 026 | 公网规则状态变更事件 |
+| `metrics_samples` | 027 | 本机与规则指标历史 |
+
+### 6.2 数据设计亮点
+
+- `proxy_hosts(hostname, listen_port)` 唯一，避免同一域名与端口被多条规则占用。
+- `proxy_custom_endpoints` 单独记录自定义 Nginx 配置的监听端点，保证自定义模式也能参与冲突校验。
+- `frp_proxies.type` 在 021 迁移中扩展到 8 种类型，并为 TCP / UDP 远程端口分别建立唯一索引。
+- `frp_runtime_status` 将“用户期望状态”和“实际进程/连接状态”分开，有助于区分手动停止和异常掉线。
+- `route_health_events` 只记录状态变化，不保存每轮原始采样，降低长期数据量。
+- `metrics_samples` 采用 `(scope, metric, value, at)` 纵向结构，增加指标不需要改表。
+
+### 6.3 数据生命周期
+
+| 数据 | 清理方式 |
+| --- | --- |
+| 会话 | 校验过期时删除；修改密码时删除其他会话 |
+| 健康事件 | 巡检按保留期清理 |
+| 指标采样 | 巡检按保留期清理 |
+| 备份归档 | 按设置中的保留份数剪枝 |
+| Nginx 配置版本 | 默认保留最近 10 个有效变化 |
+| 日志 | 由 `logstore` 与轮转策略处理 |
+
+---
+
+## 七、HTTP API 与认证面
+
+### 7.1 路由规模
+
+当前 `internal/api/router.go` 中：
+
+- 受保护路由约 113 条：使用 `SessionMiddleware + RequireAuth`；
+- 匿名路由 5 条：版本、登录状态、登录、退出、公开状态页；
+- 静态资源与 SPA fallback：非 `/api/` 路由全部交给前端。
+
+匿名接口：
+
+| 方法 | 路径 | 说明 |
+| --- | --- | --- |
+| GET | `/api/version` | 版本与默认反代端口 |
+| GET | `/api/auth/status` | 是否初始化、是否已登录 |
+| POST | `/api/auth/login` | 登录 |
+| POST | `/api/auth/logout` | 退出 |
+| GET | `/api/status-page` | 默认关闭的只读状态页 |
+
+### 7.2 API 分组
+
+| 分组 | 代表路径 | 能力 |
+| --- | --- | --- |
+| 认证 | `/api/auth/*` | 登录、退出、改密 |
+| API Token | `/api/settings/tokens` | 创建、列出、撤销 |
+| 仪表盘 | `/api/status` | 公网 IP、DDNS、证书、反代、资源和请求趋势 |
+| 本机反代 | `/api/proxies*` | 规则 CRUD、排序、流量、连接、实时日志 |
+| Nginx 配置 | `/api/proxies/{id}/nginx`、`/api/settings/nginx/*` | 自动/自定义配置、校验、回滚、版本 |
+| DDNS | `/api/ddns*` | 任务、测试、全部更新、单任务更新 |
+| 证书 | `/api/certificates*` | CA 选项、申请、SSE 日志、导入、续期、下载、删除 |
+| 设置 | `/api/settings` | 常规、通知、安全、高级设置 |
+| 日志 | `/api/logs/*` | 访问、错误、系统、SSE |
+| 指标 | `/api/metrics/history` | 分桶历史趋势 |
+| 备份 | `/api/backup*` | 导出、恢复、归档、下载、删除 |
+| 服务发现 | `/api/discovery/scan` | 扫描常见 NAS 服务端口 |
+| FRP 多服务端 | `/api/frpmulti/*` | 服务端、frpc、规则、诊断、版本下载 |
+| 公网 Agent | `/api/frpmulti/servers/{id}/agent/*` | 状态、Nginx、frps、证书、路由、漂移、指标 |
+
+### 7.3 Agent API
+
+`fonu-agent` 当前提供 20 个 `/api/v1/*` 接口，全部使用 Bearer Token：
+
+| 类别 | 接口 |
+| --- | --- |
+| 基础 | `ping`、`status` |
+| 路由 | 列表、写入、详情、删除、版本、回滚 |
+| Nginx | 安装、重载、日志 |
+| frps | 配置读取与写入、安装、启停重启 |
+| 证书 | 写入与列表 |
+| 中国 IP | `PUT /china-cidr` |
+| 指标 | `GET /metrics` |
+
+Agent 侧的重要安全措施：
+
+- SSH 安装使用 TOFU 主机密钥校验，首次记录，后续变更拒绝；
+- frps 下载只允许官方地址和固定加速前缀；
+- frps 安装包下载后校验 SHA-256；
+- Basic Auth 使用纯 Go apr1，不依赖 VPS 上的 `openssl`；
+- 写 vhost 前保留版本，`nginx -t` 失败时恢复上一个可用配置。
+
+---
+
+## 八、前端结构
+
+### 8.1 路由与页面
+
+前端共 11 条路由定义：
+
+| 路径 | 名称 | 是否公开 | 页面 |
+| --- | --- | --- | --- |
+| `/setup` | - | 重定向 | 跳转登录 |
+| `/login` | `login` | 是 | 登录 |
+| `/status` | `status` | 是 | 公开状态页 |
+| `/dashboard` | `dashboard` | 否 | 仪表盘 |
+| `/ddns` | `ddns` | 否 | DDNS |
+| `/certificates` | `certificates` | 否 | 证书管理 |
+| `/proxies` | `proxies` | 否 | 本机反向代理 |
+| `/frp` | `frp` | 否 | 内网穿透 |
+| `/frp-agent` | `frp-agent` | 否 | 公网服务端 |
+| `/public-proxy` | `public-proxy` | 否 | 公网反代 |
+| `/logs` | `logs` | 否 | 日志中心 |
+| `/settings` | `settings` | 否 | 系统设置 |
+
+路由守卫在每次受保护页面跳转前请求 `/api/auth/status`。公开状态页不做登录检查，避免匿名访问时产生无意义请求。
+
+### 8.2 页面规模
+
+| 文件 | 约行数 | 主要职责 |
+| --- | ---: | --- |
+| `ProxyView.vue` | 3150 | 本机反代规则、详情、日志、Nginx 配置 |
+| `SettingsView.vue` | 2144 | 常规、通知、安全、高级、备份、Token |
+| `AgentView.vue` | 1807 | 公网服务端、Agent、frps 生命周期、诊断 |
+| `CertificatesView.vue` | 1685 | 证书列表、申请、续期、下载、导入 |
+| `DashboardView.vue` | 1679 | 状态卡、趋势、健康、流量 |
+| `DdnsView.vue` | 1568 | DDNS 任务、记录、服务商配置 |
+| `FrpView.vue` | 1406 | frpc 服务端和穿透规则 |
+| `ProxyRemoteView.vue` | 1150 | 公网反代部署、漂移、健康、版本 |
+| `LogsView.vue` | 860 | 系统、访问、错误、FRP 日志 |
+
+这些页面都由 Composition API 直接承载大量状态和逻辑。当前结构适合快速迭代，但需要继续拆分：
+
+- `ProxyView.vue`：拆规则表单、Nginx 面板、客户端面板、日志面板；
+- `AgentView.vue`：拆服务端表单、日志弹窗、详情弹窗、延迟图；
+- `SettingsView.vue`：拆通知、安全、备份、Token、状态页卡片。
+
+### 8.3 API 客户端
+
+`web/src/api/client.ts` 统一处理：
+
+- `credentials: include`；
+- JSON 请求体；
+- 30 秒普通请求超时；
+- 10 分钟证书操作超时；
+- 错误信息归一化；
+- Blob 下载与文件名解析。
+
+`web/src/api/types.ts` 约 923 行，集中定义后端响应结构。类型覆盖较全，但仍保留旧 FRP 单体接口类型，形成历史冗余。
+
+### 8.4 前端测试
+
+已有：
+
+- `web/src/utils/status.spec.ts`：状态值到 UI 状态的映射回归；
+- `web/src/utils/format.spec.ts`：格式化函数。
+
+缺口：
+
+- API 客户端无测试；
+- 页面组件无测试；
+- 轮询与可见性行为无测试；
+- 配置差异、回滚、表单校验等高风险交互仍只能依赖类型检查与人工验证。
+
+---
+
+## 九、核心业务链路
+
+### 9.1 本机反向代理
+
+数据流：
+
+```text
+前端保存规则
+  → proxy.Store 校验域名与端口唯一性
+  → 写入 proxy_rules / proxy_hosts
+  → 生成 Nginx 配置
+  → nginx -t 校验
+  → 热重载或重启
+  → 写入流量采集与日志
+```
+
+要点：
+
+- 规则支持多域名、多端口、IPv4/IPv6 监听、HTTPS 与 HTTP 跳转；
+- 安全设置保存在 `security_json`，包括 IP 黑白名单、仅中国大陆、Basic Auth、限流、连接数限制、安全响应头等；
+- 自动模式由模板生成，自定义模式允许编辑但会解析监听端点参与冲突校验；
+- 配置写入前保留 `.bak` 与 `.versions`，失败不覆盖当前可用配置；
+- Nginx 配置版本支持列表、读取、差异对比和回滚。
+
+### 9.2 DDNS
+
+支持的服务商：
+
+- Cloudflare；
+- DNSPod；
+- 阿里云 DNS；
+- 腾讯云 DNS；
+- 火山引擎 DNS。
+
+能力：
+
+- 单任务多根域名 / 多记录；
+- 最长后缀 Zone 匹配；
+- IPv4 / IPv6；
+- 自定义固定 IP；
+- 手动测试与全部更新；
+- 定时任务按设置间隔运行，默认 5 分钟；
+- 凭证加密保存；
+- IP 变化、失败等情况进入通知系统。
+
+### 9.3 证书
+
+证书链路：
+
+```text
+选择 CA 与域名
+  → 复用 DDNS 凭证
+  → DNS-01 挑战
+  → lego 申请
+  → 写入证书目录
+  → 更新 certificates 表
+  → 重载 Nginx
+  → 前端通过 SSE 获取任务日志
+```
+
+当前 CA 相关能力：
+
+- Let's Encrypt；
+- ZeroSSL；
+- LiteSSL；
+- LiteSSL 强制 EAB；
+- 可配置 DNS 递归解析器，避免容器内 `127.0.0.11` 无法解析权威 NS；
+- 支持导入 PEM、下载 ZIP / 证书 / 私钥；
+- 每天执行续期巡检，按到期阈值提醒。
+
+### 9.4 FRP 与公网 Agent
+
+FRP 模块当前支持：
+
+- 多台公网 frps；
+- 8 种穿透类型：tcp、udp、http、https、tcpmux、stcp、sudp、xtcp；
+- frpc 多版本下载、启用与删除；
+- frpc 配置生成与进程管理；
+- frps.toml 同源生成；
+- 服务端认证方式：token、none、OIDC；
+- frpc 流量、连接数与速率；
+- 服务端 TCP / 登录 / 代理 / DNS / 归属地诊断；
+- SSH 一键安装、升级、卸载 `fonu-agent`；
+- Agent 状态、Nginx、frps 配置、证书、日志、指标；
+- 公网反代 vhost 部署、漂移检测、版本与回滚；
+- 四段健康检查：DNS、证书、隧道、回源服务。
+
+主要风险点：
+
+- `internal/frp/service.go` 和 `internal/agent/server.go` 都是超大文件；
+- 宿主机 Nginx 模板与 Agent Nginx 模板存在两份实现，需要人工保持同步；
+- Agent 与主程序之间存在版本兼容契约，旧 Agent 通过 404/405 映射升级提示，但接口演进仍需谨慎；
+- VPS 上的系统环境差异大，尤其是 Nginx 安装位置、systemd、宝塔环境与 PATH。
+
+### 9.5 监控、健康与通知
+
+调度器每 2 分钟执行 `monitor`：
+
+- 本机 CPU、内存、磁盘；
+- 资源阈值；
+- 本机规则流量；
+- 公网规则 DNS / 证书 / 隧道 / 服务四段健康；
+- frps 服务端掉线；
+- Agent 不可达；
+- 公网 vhost 配置漂移。
+
+通知渠道：
+
+- SMTP 邮件；
+- Webhook；
+- Telegram；
+- Bark；
+- ntfy；
+- Gotify；
+- 企业微信；
+- 钉钉；
+- 飞书。
+
+告警策略已具备：
+
+- 连续失败阈值；
+- 恢复通知；
+- 资源告警冷却；
+- 配置漂移冷却；
+- 登录失败窗口统计。
+
+### 9.6 指标、日志与流量
+
+指标：
+
+- 本机资源与每条公网规则流量写入 `metrics_samples`；
+- 查询时按桶取平均，前端支持 1 小时、24 小时、7 天趋势；
+- 避免每加一个指标就改表结构。
+
+日志：
+
+- `app.log`：应用系统日志；
+- `access.log`：本机 Nginx 访问日志；
+- `error.log`：本机 Nginx 错误日志；
+- `frpc.log`：FRP 客户端日志；
+- 日志中心支持分页、筛选和 SSE 实时访问/错误日志。
+
+流量：
+
+- `traffic.Collector` 跟踪 access log 增量；
+- 汇总到规则和域名；
+- 计算累计上下行、速率与当前连接数；
+- 与监控巡检共用主机维度聚合算法，减少口径漂移。
+
+### 9.7 备份与恢复
+
+能力：
+
+- 手动导出；
+- 上传恢复；
+- 定时自动备份；
+- 服务端归档列表；
+- 下载、恢复、删除；
+- 恢复前校验归档；
+- 按保留份数剪枝；
+- 自动备份失败通知。
+
+恢复会覆盖数据库与证书等关键数据，前端需要二次确认。由于 SQLite 正在运行，恢复后推荐重启 Fonu。
+
+---
+
+## 十、后台调度
+
+`internal/app/app.go` 注册的任务：
+
+| 任务 | 间隔 | 作用 |
+| --- | --- | --- |
+| DDNS | 默认 5 分钟，可在设置中调整 | 检测公网 IP 并同步 DNS |
+| ACME | 24 小时 | 证书续期与到期提醒 |
+| 中国 IP 段 | 默认 24 小时，可在设置中调整 | 下载并生成 Nginx geo 配置 |
+| monitor | 2 分钟 | 资源、隧道、服务端、Agent、漂移巡检与指标采样 |
+| backup | 24 小时 | 自动备份并按策略保留 |
+
+调度器还负责：
+
+- 任务 panic 恢复；
+- 非正间隔跳过；
+- 应用退出时通过 Context 取消。
+
+---
+
+## 十一、部署与运维
+
+### 11.1 推荐部署形态
+
+飞牛 fnOS 推荐：
+
+```bash
+docker run -d \
+  --name fonu \
+  --net=host \
+  -v /vol1/docker/fonu-data:/data \
+  --restart unless-stopped \
+  fonu:local
+```
+
+管理入口 `http://<NAS-IP>:6893`，默认反代端口 18080/9443，避免和系统 Nginx 抢占 80/443。
+
+### 11.2 升级方式
+
+三种方式：
+
+1. 本地源码：`docker compose up -d --build`；
+2. 单文件编排：保留 `docker-compose.hub.yml`，重新执行 `docker compose up -d --build`；
+3. 原生安装：使用 `scripts/build-linux.ps1` 构建包，再由 `scripts/fonu-install.sh` 安装。
+
+升级脚本：
+
+- `scripts/upgrade.sh`：拉代码、构建、重建、健康检查，支持 `--no-pull` 和回滚；
+- `scripts/upgrade-hub.sh`：仅使用编排文件的部署升级；
+- `scripts/agent-install.sh`：安装 `fonu-agent`。
+
+### 11.3 数据持久化
+
+默认使用命名卷 `fonu-data`。如需绑定宿主机目录，在 `.env` 中设置：
+
+```dotenv
+FONU_DATA_PATH=/vol1/docker/fonu-data
+```
+
+Compose 约定以 `/` 或 `.` 开头的值解释为 bind mount，其余字符串仍是命名卷。
+
+`FONU_SESSION_SECRET` 同时承担凭据解密，已有数据后不能随意替换，否则 DDNS、FRP、通知和 SSH 等密文可能无法解密。
+
+---
+
+## 十二、工程化、测试与质量门禁
+
+### 12.1 CI
+
+`.github/workflows/ci.yml` 已实现完整验证顺序：
+
+1. Checkout；
+2. 安装 Node 22；
+3. `npm ci`；
+4. `npm run build`；
+5. `npm test`；
+6. 将 `web/dist` 同步到 `cmd/fonu/web/dist`；
+7. 安装 Go；
+8. `go vet ./...`；
+9. `go test ./... -count=1`；
+10. `go build ./...`。
+
+顺序不可颠倒，因为 `cmd/fonu/main.go` 使用 `//go:embed all:web/dist`，干净检出时前端产物必须先生成。
+
+当前 CI 尚未开启 `gofmt -l` 卡口，原因是仓库仍有历史未格式化文件。建议在集中执行一次 `gofmt -w` 后开启。
+
+### 12.2 发布工作流
+
+- `docker-release.yml`：tag 或手动触发，构建 amd64/arm64 镜像并生成多架构 manifest；
+- `github-release.yml`：根据 `CHANGELOG.md` 生成 GitHub Release。
+
+### 12.3 测试覆盖
+
+Go 测试分布较广，`nginx` 包测试最多，其次为 `frp`、`acme`、`api`。
+
+当前没有测试文件的包：
+
+- `internal/discovery`；
+- `internal/secret`；
+- `internal/service`；
+- `internal/settings`；
+- `internal/version`；
+- `cmd/fonu`；
+- `cmd/fonu-agent`。
+
+优先级较高的补测：
+
+1. `internal/service` 的规则保存、Nginx 自定义配置与回滚；
+2. `internal/settings` 的类型转换、默认值和迁移；
+3. `internal/secret` 的加解密与密钥错误提示；
+4. 路由与中间件测试，确保新增受保护接口不会漏鉴权；
+5. Agent `readLimitState`、`writeLimitState` 与配置回滚；
+6. 前端 API 客户端和轮询组合式函数。
+
+### 12.4 本次验证
+
+本次分析实际执行：
+
+```bash
+go test ./... -count=1
+go vet ./...
+cd web && npm run typecheck
+cd web && npm test
+```
+
+结果：
+
+- Go：所有含测试包通过；
+- Go vet：无输出，退出码 0；
+- 前端类型检查：通过；
+- 前端测试：2 个测试文件、13 条测试全部通过。
+
+### 12.5 格式化
+
+仓库目前仍存在历史未格式化文件。本次只做过读取和测试，没有批量执行 `gofmt -w`，以免把格式化噪音混入用户当前未提交的改动。
+
+---
+
+## 十三、当前风险与技术债
+
+### 13.1 功能与兼容性
+
+1. **旧 `/api/frp` 客户端残留**
+   - `web/src/api/client.ts` 仍定义 `getFRP`、`saveFRP`、`getFRPStatus`、`syncFRPDomains`、`getFRPLogs`；
+   - `web/src/views/DdnsView.vue` 在 `init()` 中调用 `api.getFRP()`；
+   - 后端当前只注册 `/api/frpmulti/*`，因此该请求失败后进入 `catch`，`frpEnabled` 被设为 `false`；
+   - 影响：DDNS 页可能无法显示与 FRP 相关的提示；
+   - 建议：删除旧类型与旧方法，或改为调用 `/api/frpmulti/status`。
+
+2. **Agent 版本兼容需要长期维护**
+   - 主程序通过 404/405 识别旧 Agent，并提示升级；
+   - 新接口应继续沿用最低版本提示，避免前端只看到网络错误。
+
+3. **宿主机与 Agent 的 Nginx 模板双份实现**
+   - 一边是 `internal/nginx`，一边是 `internal/agent`；
+   - 修改一处忘记另一处会造成本机与公网行为不一致；
+   - 建议抽共享模板包，至少共享安全指令、限流、geo、WebSocket、TLS 片段。
+
+### 13.2 安全
+
+1. **初始管理员密码写入应用日志**
+   - `auth.EnsureDefaultAdmin` 记录用户名和密码；
+   - `logstore.appendSystemAttrs` 会把密码原样拼进系统日志；
+   - `GET /api/logs/system` 可读取该系统日志；
+   - 建议只在进程首次启动时输出到终端一次，不写入持久日志；或生成一次性初始密码文件并设置 0600。
+
+2. **Agent 默认明文 HTTP 监听**
+   - 默认 `:7700`，Bearer Token 直接在网络中传输；
+   - 如果直接暴露公网，需要 HTTPS、内网限制或前置反向代理；
+   - 建议默认绑定 `127.0.0.1`，由 Nginx 或隧道暴露，并把公网绑定作为显式选项。
+
+3. **Agent Token 比较未使用常量时间**
+   - Agent 使用字符串比较；
+   - 建议使用 `crypto/subtle.ConstantTimeCompare`。
+
+4. **Agent 限流状态反序列化失败会静默清空**
+   - `readLimitState` 忽略 JSON 错误；
+   - 后续写入可能删除 zone 文件；
+   - 建议解析失败返回错误并保留原文件。
+
+5. **备份上传仍允许 64MB**
+   - 已有 `CreateTemp` 修复路径穿越；
+   - 仍建议降低上限并增加频率限制。
+
+### 13.3 性能与并发
+
+1. **SQLite 单连接**
+   - 当前实现简单可靠，但监控查询、日志、指标与 API 会竞争同一连接；
+   - 可通过缩短事务、减少大查询、为高频读增加轻量缓存来缓解。
+
+2. **前端大页面与高频轮询**
+   - 多个页面存在 15 秒轮询，仪表盘流量轮询更快；
+   - 轮询请求应加入 in-flight 互斥，并在页面隐藏时暂停；
+   - 可以统一抽 `useVisibilityPolling`。
+
+3. **巨型后端文件**
+   - `internal/frp/service.go` 约 1805 行；
+   - `internal/agent/server.go` 约 1551 行；
+   - 建议按能力拆分文件，例如 rate limit、nginx template、frps install、route versions、diagnostics。
+
+### 13.4 维护性
+
+1. **前端样式与弹窗外壳重复**
+   - 多个页面重复实现左列表、弹窗外壳和状态色；
+   - 建议抽 `SidebarList.vue`、`ModalShell.vue` 和统一状态令牌。
+
+2. **硬编码颜色仍需收敛**
+   - `variables.css` 已有品牌令牌；
+   - 页面中仍有大量直接色值与重复色板。
+
+3. **旧文档时效**
+   - `project-audit-2026-09-24.md` 基于 v1.2.6，其中很多 P0/P1 已实施；
+   - 阅读旧审查时应以 CHANGELOG、当前源码和本文档为准。
+
+4. **归档目录删除尚未提交**
+   - `internal/frp-1.0.2` 与 `FrpView-1.0.2.vue` 在工作树中已删除但未提交；
+   - 分析时保持原样，没有回退或提交。
+
+---
+
+## 十四、建议改进路线
+
+### P0：先处理明确问题
+
+1. 修正 `DdnsView` 对旧 `/api/frp` 的调用，切到 `/api/frpmulti/status`。
+2. 初始管理员密码不再写入持久应用日志。
+3. Agent Token 比较改为常量时间。
+4. `readLimitState` 解析失败时拒绝覆盖原状态。
+5. 明确 Agent 默认监听策略，最好默认仅本机或要求 HTTPS。
+
+### P1：降低核心模块风险
+
+1. 抽共享 Nginx 模板包，统一本机与 Agent 的安全、限流、geo、TLS 逻辑。
+2. 拆分 `internal/frp/service.go` 与 `internal/agent/server.go`。
+3. 拆分 `ProxyView.vue`、`SettingsView.vue`、`AgentView.vue`。
+4. 为路由鉴权、配置回滚、Agent 版本兼容补测试。
+5. 前端轮询统一抽 composable，加入互斥与页面可见性控制。
+
+### P2：工程质量提升
+
+1. 全仓执行一次 `gofmt -w`，随后在 CI 中开启 `gofmt -l` 卡口。
+2. 清理旧 FRP 类型、旧 API 方法和未使用样式。
+3. 收敛颜色令牌与重复弹窗外壳。
+4. 增加前端 API 客户端测试与关键页面组件测试。
+5. 为 SQLite 高频查询建立基准，确认单连接是否满足长期指标数据。
+
+### P3：能力增强
+
+1. 加密迁移包：导出并导入含敏感凭据的完整实例。
+2. 审计日志：记录谁在何时修改了规则、服务端、证书和设置。
+3. 2FA / TOTP 与登录设备管理。
+4. SMART 磁盘健康与 UPS 状态。
+5. Prometheus `/metrics` 导出。
+6. 状态页事故记录与服务入口聚合页。
+
+---
+
+## 十五、关键源码索引
+
+| 目标 | 文件 |
+| --- | --- |
+| 应用装配 | `internal/app/app.go` |
+| 配置 | `internal/config/config.go` |
+| 数据库迁移 | `internal/db/db.go`、`migrations/*.sql` |
+| HTTP 路由 | `internal/api/router.go` |
+| 认证中间件 | `internal/api/middleware.go` |
+| 登录与会话 | `internal/auth/auth.go`、`internal/api/auth_handler.go` |
+| 本机反代 | `internal/proxy/proxy.go`、`internal/service/nginx_config.go` |
+| Nginx 生成与重载 | `internal/nginx/*.go` |
+| DDNS | `internal/ddns/*.go` |
+| 证书 | `internal/acme/*.go`、`internal/certificate/*.go` |
+| FRP 主服务 | `internal/frp/service.go` |
+| FRP 模型 | `internal/frp/model.go` |
+| Agent 客户端 | `internal/frp/agent_client.go` |
+| 公网 Agent | `internal/agent/server.go`、`internal/agent/versions.go` |
+| 监控巡检 | `internal/monitor/monitor.go` |
+| 通知 | `internal/notify/*.go` |
+| 日志 | `internal/logstore/*.go` |
+| 流量 | `internal/traffic/collector.go` |
+| 指标 | `internal/metrics/*.go` |
+| 备份 | `internal/backup/*.go` |
+| 前端路由 | `web/src/router/index.ts` |
+| 前端 API | `web/src/api/client.ts`、`web/src/api/types.ts` |
+| 前端布局 | `web/src/layouts/AppLayout.vue` |
+| CI | `.github/workflows/ci.yml` |
+| 容器构建 | `Dockerfile`、`docker-compose*.yml` |
+
+---
+
+## 十六、总结
+
+Fonu 已经从一个 Nginx 反代面板发展为覆盖「本地入口、DNS、证书、内网穿透、公网 Agent、监控告警、备份恢复」的 NAS 公网访问控制面。
+
+它的优势在于：功能完整、模块边界总体清楚、迁移与部署链路成熟、关键配置有版本和回滚、自动化任务覆盖主要运维场景。
+
+当前最需要做的不是继续横向增加功能，而是先把 FRP / Agent 这条最复杂的链路拆小，把旧接口残留和日志泄密等明确问题清掉，再补上路由鉴权、配置回滚和 Agent 兼容测试。这样后续增加迁移包、审计、2FA、Prometheus 等能力时，才不会把复杂度继续堆进两个超大服务文件。