Docker 基础设施文档维护指南 (SOP)

1. 核心原则 (Core Principles)

在维护文档时，必须严格遵守以下原则：

1.单一事实来源 (Single Source of Truth): 文档必须反映服务器的真实状态。如果文档说端口是 8001，但服务器上是 8002，那就是文档错了，必须立即修正。2.变更即记录 (Log Changes as They Happen): 不要想着“等我有空了再统一更新”。修改配置 (docker-compose.yaml) 的同时，必须更新文档。3.安全脱敏 (Security Redaction): 文档中严禁出现明文密码、API Key 或未脱敏的公网 IP。4.以恢复为目的 (Recovery Oriented): 假设服务器明天爆炸，这份文档必须包含足够的信息让你在 1 小时内重建所有服务。

2. 维护触发条件 (Triggers)

当发生以下任一操作时，必须更新《基础设施架构文档》：

A. 新增服务 (Add Service)

•动作: 部署了一个新容器（例如安装 Uptime Kuma）。•文档更新点:•服务清单: 记录服务名、镜像版本。•端口管理: 分配并记录新的宿主机端口（如 3001），确保不冲突。•数据路径: 记录 Bind Mount 的本地路径（如 ~/docker-infra/uptime-kuma/data）。•网络拓扑: 记录它加入了哪个网络（nexty-public 还是 gateway-net）。

B. 变更配置 (Configuration Change)

•动作: 修改了 docker-compose.yaml。•文档更新点:•网络变更: 例如把 n8n 从只连 gateway-net 改为同时连接 nexty-public。•存储迁移: 例如从 Docker Volume 迁移到 Bind Mount。•端口修改: 因冲突修改了宿主机映射端口。

C. 接入层变更 (Ingress Change)

•动作: 在 Cloudflare Zero Trust 后台修改了 Tunnel 配置。•文档更新点:•路由表: 更新 域名 -> 内部服务 的映射关系。•检查: 确认新域名是否符合“扁平化”原则（避免四级域名）。

3. 定期审计流程 (Regular Audit Workflow)

建议 每月 执行一次“文档 vs 现实”的核对，防止文档腐烂。

步骤 1: 获取实时快照

使用我们在服务器上保存的脚本 audit_docker.sh 获取当前真实状态。

# 在服务器执行./audit_docker.sh

(如果没有脚本，使用 docker ps 和 docker inspect 手动查看)

步骤 2: 核对关键字段

将脚本输出的表格与 Notion 文档进行比对，重点检查：

1.端口漂移: 是否有容器的端口被临时改过但没记录？2.幽灵容器: 是否有文档里写了，但服务器上已经删掉的废弃容器？3.野生容器: 是否有测试时随手起的容器（如 test-redis）忘记删除了？

步骤 3: 修正与同步

•如果发现不一致，以服务器现状为准更新文档（除非服务器现状是错误的配置）。•清理服务器上的“野生容器”和未使用的 Volume (docker volume prune)。

4. 端口分配标准 (Port Allocation Standard)

为了避免未来的“端口地狱”，请严格遵守以下分段策略：

规则:

1.分配新端口前，先 Ctrl+F 搜索文档，确认未被占用。2.优先使用 80xx 段作为 Web 面板的统一入口。

5. 灾难恢复演练 (DR Drill) 可选

频率: 每 3-6 个月（或重大架构变更后）。

验证方法:

1.模拟: 假设需要在一台新服务器上恢复 n8n。2.检查: 文档里是否记录了 n8n 的 docker-compose.yaml 路径？是否记录了数据卷在宿主机的哪个文件夹？3.结论: 如果只看文档就能把服务跑起来，说明文档合格。

📝 附录：自动化审计脚本

(将此脚本保存在服务器 ~/docker-infra/audit_docker.sh 并赋予执行权限 chmod +x)

#!/bin/bash# Docker Infrastructure Audit Script# 用于快速生成文档所需的当前状态表格echo "| Container Name | Image | Networks | Ports (Host:Container) | Mounts (Host -> Container) |"echo "| :--- | :--- | :--- | :--- | :--- |"docker inspect --format '{{.Name}}|{{.Config.Image}}|{{range $k, $v := .NetworkSettings.Networks}}{{$k}}, {{end}}|{{range $p, $conf := .NetworkSettings.Ports}}{{if $conf}}{{range $conf}}{{.HostPort}}:{{$p}}, {{end}}{{end}}{{end}}|{{range .Mounts}}{{if eq .Type "bind"}}{{.Source}} -> {{.Destination}}{{else if eq .Type "volume"}}Vol: {{.Name}} -> {{.Destination}}{{end}}, {{end}}' $(docker ps -q) | \sed 's|/||' | \while IFS='|' read -r name image networks ports mounts; do    # 清理末尾逗号    networks=$(echo "$networks" | sed 's/, $//')    ports=$(echo "$ports" | sed 's/, $//')    mounts=$(echo "$mounts" | sed 's/, $//')    # 输出 Markdown 表格行    echo "| **$name** | \`$image\` | $networks | $ports | \`$mounts\` |"done