服务命名和端口规划，是 HomeLab 日常排障的导航图。

\n
服务少的时候，端口随便填也能记住。一个 8080，一个 9000，再加几个收藏夹，短期没问题。服务多起来以后，端口冲突、反向代理上游、监控目标、备份目录、容器名和项目目录都会互相牵连。命名和端口不规划，排障时就会在一堆相似名字里来回猜。

我把命名和端口表当成 HomeLab 的导航图。它不需要复杂，但要稳定、可搜索、能和 Compose 对上。

名字尽量一条线

同一个服务，我希望这些地方使用同一个名字：项目目录、Compose service、container_name、反代 upstream、备份目录、监控名称。比如都叫 uptime-kuma，就不要一会儿叫 monitor，一会儿叫 status-page。

/srv/docker/uptime-kuma/
  compose.yml
  data/
  backup/
container: uptime-kuma
proxy upstream: uptime-kuma:3001
backup: backup-uptime-kuma-2026-06-13.tar.gz

这样做的好处在恢复时最明显。看到日志里的容器名，可以直接定位目录；看到备份包，可以知道对应哪个 Compose；反代 502 时，也能快速判断上游服务名是不是写错。

端口按用途分段

我不会追求每个端口都很好记，而是按用途分段。比如：

这张表不一定适合所有人，但要有自己的规则。新增服务前先查表，避免“先随便填一个，等冲突再说”。端口规划最大的价值不是记忆，而是减少冲突和减少猜测。

能不映射就不映射

不是所有服务都需要宿主机端口。放在反向代理后面的 Web 服务，可以只暴露给代理网络；数据库、缓存、内部任务服务更不应该为了方便直接映射到宿主机。

services:
  uptime-kuma:
    image: louislam/uptime-kuma:1.23.13
    container_name: uptime-kuma
    restart: unless-stopped
    ports:
      - "13001:3001"
    volumes:
      - /srv/docker/uptime-kuma/data:/app/data

如果某个服务已经通过反代提供入口，后续可以评估是否保留直接端口。保留也可以，但要在端口表里写明用途：是内网备用入口，还是只给调试用。没有说明的端口，半年后基本都会变成疑点。

端口表要跟 Compose 一起维护

端口表不要只放在脑子里。我会在 /srv/docker/README.md 或单独的 ports.md 里维护，新增服务时同时更新。内容可以很简单：

| 服务 | 目录 | 宿主机端口 | 容器端口 | 入口 | 备注 |
|---|---|---:|---:|---|---|
| uptime-kuma | /srv/docker/uptime-kuma | 13001 | 3001 | 内网/反代 | 状态监控 |
| portainer | /srv/docker/portainer | 12000 | 9000 | 内网 | Docker 管理 |

表里一定要有目录。只记录端口不够，排障时还要知道配置在哪里、数据在哪里。迁移机器时，这张表能直接变成检查清单。

排查冲突时先看事实

遇到容器启动失败，提示端口被占用，我会先查当前监听和容器端口：

docker ps --format "table {{.Names}}\t{{.Ports}}"
lsof -iTCP -sTCP:LISTEN -n -P
docker compose ls
docker compose ps

不要只凭记忆改端口。先确认是谁占用，再决定是停旧服务、改新服务，还是把入口收敛到反向代理。改完以后同步端口表和 Compose，否则下一次还是会冲突。

命名和端口规划不是仪式感，它直接影响恢复速度。名字一致，端口有段，目录能对上，迁移和排障时就少很多绕路。HomeLab 服务越多，这种朴素规则越值钱。