diff --git a/docs/development/implementation-plan.md b/docs/development/implementation-plan.md index 3b0693e..93646ed 100644 --- a/docs/development/implementation-plan.md +++ b/docs/development/implementation-plan.md @@ -357,7 +357,7 @@ OpenAPI 结构契约由 Go 测试在双平台 CI 执行。 - [ ] Add the production Kubernetes mTLS identity overlay, certificate rotation and unique elastic Worker identity wiring. - [x] Add low-cardinality Prometheus metrics and structured secret-safe logs. -- [ ] Document backup, recovery, rollout, rollback, capacity, kernel, file descriptor, +- [x] Document backup, recovery, rollout, rollback, capacity, kernel, file descriptor, NAT/conntrack, and incident runbooks. 当前进度(2026-08-02):已接入 Checker 任务流指标 diff --git a/docs/docs_test.go b/docs/docs_test.go index 686501c..b3aea73 100644 --- a/docs/docs_test.go +++ b/docs/docs_test.go @@ -77,6 +77,22 @@ func TestDocumentedGoCommandsReferenceExistingTargets(t *testing.T) { } } +func TestRunbookCoversHostAndNetworkCapacityBaseline(t *testing.T) { + content := readDocument(t, filepath.Join(repositoryRoot(t), "docs", "operations", "runbook.md")) + for _, required := range []string{ + "## 8. 备份与恢复", + "## 10. 主机与网络容量基线", + "ulimit -n", + "conntrack", + "NAT", + "回滚", + } { + if !strings.Contains(content, required) { + t.Errorf("runbook does not document %q", required) + } + } +} + func markdownDocuments(t *testing.T, repositoryRoot string) []string { t.Helper() documents := []string{filepath.Join(repositoryRoot, "README.md")} diff --git a/docs/operations/runbook.md b/docs/operations/runbook.md index 1ac3948..5fefcc9 100644 --- a/docs/operations/runbook.md +++ b/docs/operations/runbook.md @@ -349,3 +349,41 @@ ownership epoch、活动池 TTL、短期幂等窗口、outbox 和配置 Revision 5. 所有副本应用后撤销旧 Secret。 Proxy 凭据轮换必须增加 `credentialVersion`,确保唯一键不会把新旧凭据错误合并。 + +## 10. 主机与网络容量基线 + +在预发布压测和每次生产扩容前,记录 Gateway 节点、容器运行时和 Pod 内的下列只读基线; +不要在故障处理中临时提高内核限制,任何变更都必须经过压测和变更评审。 + +```bash +ulimit -n +cat /proc/self/limits | grep 'open files' +sysctl fs.file-max net.core.somaxconn net.ipv4.ip_local_port_range +test -r /proc/sys/net/netfilter/nf_conntrack_max && cat /proc/sys/net/netfilter/nf_conntrack_max +ss -s +``` + +同时从节点或受监控的 NAT 网关采集 conntrack 使用率、丢包、重传、SYN backlog、TIME_WAIT、 +端口分配失败与 SNAT 端口耗尽事件。`conntrack -L` 会遍历整个表,不得在高峰时将它作为 +常规排障命令;优先使用节点监控或 `conntrack -S` 的聚合计数。 + +Gateway 的文件描述符预算必须按实际连接模型计算,而不是仅按 QPS:每条活跃 CONNECT +隧道通常占用客户端和上游两个 socket;HTTP 上游并发、idle 连接池、监听 socket、日志和 +运行时也会占用描述符。部署前确认 Pod 内 `ulimit -n`、容器运行时 `LimitNOFILE` 与节点 +`fs.file-max` 均高于下式结果并保留至少 20% 余量: + +```text +fd_budget = 2 * max_active_connect_tunnels + + max_concurrent_http_upstreams + + max_idle_transport_connections + + process_reserve +``` + +如果节点通过 NAT 访问上游,源端口和 conntrack 表同样构成硬上限。压测报告必须记录每个 +节点的 egress IP 数、可用临时端口范围、NAT/SNAT 设备限制与单目标连接分布;单一 egress IP +不足时应在发布前增加 egress IP 或拆分节点池,不能依靠无限重试掩盖端口耗尽。 + +建议将 FD、conntrack、NAT 端口利用率、SYN overflow、TCP retransmit、TIME_WAIT、CPU、RSS +和 Gateway p99 作为同一份容量证据采集。任何一项超过预设预警线时停止扩容或发布,先降低 +新连接速率并保留现有 CONNECT 隧道排空;回滚到兼容镜像或配置 revision 后,再根据原始 +指标分析根因。 diff --git a/docs/requirements/completion-audit.md b/docs/requirements/completion-audit.md index 7c3e0a1..10f35f1 100644 --- a/docs/requirements/completion-audit.md +++ b/docs/requirements/completion-audit.md @@ -108,6 +108,10 @@ mTLS 运行拓扑,并由配置、证书、命令装配和部署契约测试覆 生产环境仍必须通过独立 Overlay 为每个弹性 Worker 注入唯一、可轮换的身份与证书,且 容器端到端启动仍待具备镜像网络的环境验证。 +运维手册已覆盖管理面/活动池恢复顺序、发布与兼容回滚、Secret 轮换、容量计算,以及 +主机内核、文件描述符、NAT/conntrack 的只读基线和证据采集要求;这些文档不替代真实环境 +的备份恢复、驱逐或容量演练。 + ## 3. 后续实现范围 以下已有设计、接口或部署位置,但尚无端到端生产实现: