From b2a47456125fae463429e5cb430ca1383c336411 Mon Sep 17 00:00:00 2001 From: Codex Date: Thu, 28 May 2026 10:33:46 +0000 Subject: [PATCH] docs: document HWLAB FRP maintenance --- docs/reference/g14.md | 2 ++ docs/reference/hwlab.md | 12 ++++++++++++ 2 files changed, 14 insertions(+) diff --git a/docs/reference/g14.md b/docs/reference/g14.md index 57396334..4364d6f9 100644 --- a/docs/reference/g14.md +++ b/docs/reference/g14.md @@ -61,6 +61,8 @@ The fixed `v0.2` runtime namespace is `hwlab-v02`. The intended public FRP alloc - Cloud Web browser entry: `http://74.48.78.17:19666/`. - API/edge entry and live health: `http://74.48.78.17:19667/health/live`. +Master-side FRP server maintenance for HWLAB public ports is documented in `docs/reference/hwlab.md#hwlab-frp-维护`; keep the detailed allowlist, restart boundary and verification sequence there instead of duplicating another runbook in this G14 node reference. + The `v0.2` CI/CD integration must be additive: add a `v0.2` source watcher, GitOps desired-state lane, Argo CD Application, namespace resources, artifact catalog, and `deploy.json` environment only when they target `v0.2`/`hwlab-v02` explicitly. Do not retarget the existing `G14` poller, DEV/PROD Argo Applications, DEV/PROD runtime paths, or existing namespace resources to bootstrap `v0.2`. Do not turn `v0.2` expansion governance into a stack of broad compatibility gates. The stable control points are branch, GitOps branch, namespace, runtime path, Argo Application, FRP ports and generated-output ownership. Legacy DEV/D601/main preflights that block the `v0.2` lane should be removed from that lane, not patched with fallback or legacy modes. Naming, RBAC scope, cleanup policy, resource quota and rollback order are design decisions or runbook entries unless they protect a concrete high-value risk that cannot be enforced by the fixed boundaries above. diff --git a/docs/reference/hwlab.md b/docs/reference/hwlab.md index c6fe4b8b..0b66d634 100644 --- a/docs/reference/hwlab.md +++ b/docs/reference/hwlab.md @@ -34,6 +34,18 @@ - 旧公网 `:6666` 和 `:6667` 不是浏览器验收入口；内部 k3s service 仍可使用 `6667` 作为服务端口。 - 当前 G14 入口由 G14 侧公开代理承担；不要把 master 上的其他 UniDesk frontend/backend-core 路径误判为 HWLAB 前端。D601 legacy `16666/16667` 的 FRP 说明只用于历史对照。 +## HWLAB FRP 维护 + +HWLAB 公网 FRP server 由 master server 上的 `hwlab-frps-dev` 容器承担，容器使用 host network，并把 `/opt/hwlab-frp/frps.dev.toml` 只读挂载到 `/etc/frp/frps.toml`。这个 server 侧 allowlist 是 UniDesk 指挥侧维护对象，不属于 G14 k3s GitOps desired state；G14 侧 `frpc` ConfigMap/Deployment 只负责各 runtime namespace 的客户端 tunnel。 + +新增或恢复 HWLAB 公网入口时，先判断问题是否只是 server 侧 `allowPorts` 缺口。若 `frpc` 日志出现 `port not allowed`，优先在 master server 修改 `/opt/hwlab-frp/frps.dev.toml` 的 `allowPorts`，而不是改 DEV/PROD/v0.2 的 GitOps、Service 或 `frpc` ConfigMap。修改前保留一份本机备份，例如 `/opt/hwlab-frp/frps.dev.toml.bak-`；修改后只重启 `hwlab-frps-dev`，不要重建镜像、清理 Docker volume、重启无关 UniDesk/HWLAB 服务或触碰数据库状态。 + +当前 HWLAB FRP server allowlist 至少应覆盖 legacy `16666/16667`、G14 DEV `17666/17667`、G14 PROD `18666/18667`、G14 `v0.2` `19666/19667`，以及仍被明确使用的维护端口。新增端口必须对应一个明确的 namespace/runtime 入口，不能把大范围端口段作为默认放行策略。 + +FRP 维护验证顺序是：确认 `hwlab-frps-dev` 容器仍挂载 `/opt/hwlab-frp/frps.dev.toml`；重启后用 `ss -ltnp` 或等价只读命令确认 `frps` 正在监听 `7000` 和目标公网端口；再在目标 namespace 查看 `frpc` 日志，确认对应 proxy `start proxy success`；最后分别验证新增入口和既有 DEV 入口。`v0.2` 验证使用 `http://74.48.78.17:19666/` 与 `http://74.48.78.17:19667/health/live`，DEV 回归验证使用 `http://74.48.78.17:17666/` 与 `http://74.48.78.17:17667/health/live`。 + +FRP 文档、issue 和日志只能记录端口、容器名、ConfigMap 名、Secret 对象/key 是否存在和健康摘要；不得记录 Secret value、provider token、完整 DB URL、Codex auth JSON 或其他凭据内容。 + ## 门禁最小化与扩容治理 不要滑向不必要的复杂门禁是 HWLAB 指挥侧通用原则。G14 DEV/PROD、`v0.2` 扩容、CI/CD 迁移、运行面热修和文档治理都应优先靠固定边界、清晰命名、唯一真相源、标准入口和长期参考文档收敛，不要把每个设计约定、运行策略或回滚手册都做成新的 preflight、guard、gate 或报告生成器。