Docker 部署待办应用常见问题排查：端口、备份与升级

自托管待办应用的部署本身通常只要 10 分钟（参考私有化部署指南），真正消耗时间的是之后遇到的各种小问题。本文汇总自托管社区里最高频的 8 个问题，按"现象 → 原因 → 解法"整理，建议收藏。

一、端口类：容器跑起来了，但页面打不开

问题 1：curl localhost:8080 无响应

排查顺序：

1. docker ps 确认容器状态是 Up 而不是 Restarting（反复重启说明配置有错，docker logs 容器名 看日志）
2. 确认端口映射存在：docker ps 的 PORTS 列应显示 0.0.0.0:8080->80/tcp
3. 云服务器上检查安全组 / 防火墙是否放行该端口——这是新手问题里占比最高的一项

问题 2：本机能访问，局域网其他设备不行

通常是服务绑定到了 127.0.0.1 而不是 0.0.0.0，或防火墙未放行。Docker 端口映射请始终写 -p 8080:80 而不是 -p 127.0.0.1:8080:80（除非你明确只想本机访问）。

二、数据类：升级或重建容器后数据丢了

问题 3：重新拉取镜像后，所有任务消失

Docker 容器是临时的，数据必须放在 volume 或宿主机目录。正确姿势：

docker run -d \
  -v /opt/itodo/pgdata:/var/lib/postgresql/data \
  itodo-api:latest

数据放在 /opt/itodo/pgdata 后，升级只是换镜像重建容器，数据不受影响。没有挂载就升级，是自托管数据丢失的第一大原因。

问题 4：不确定数据存在哪里

docker inspect 容器名 | grep -A 10 Mounts 查看容器的挂载点。原则：数据库目录、上传的附件目录、配置文件，三者都必须有挂载。

三、备份类：出事之前的 5 分钟

问题 5：备份该备份什么？

最小备份集是三样：数据库、附件目录、.env / 配置文件。数据库建议用 pg_dump 做逻辑备份而不是直接拷数据目录（热拷贝可能不一致）：

docker exec itodo-db pg_dump -U postgres todo_api > backup_$(date +%F).sql

问题 6：备份放哪？

记住 3-2-1 原则的简化版：本机一份 + 异地一份（对象存储 / 另一台机器 / 离线硬盘）。备份数据库和待办应用在同一台机器上，等于没有备份。再加一个 cron 每日自动执行。

四、升级类：想更新又怕出问题

问题 7：升级的正确流程

1. 先备份（问题 5 的命令）
2. docker pull 新镜像
3. 停旧容器、起新容器（数据在 volume 里，无缝衔接）
4. 打开应用验证：登录、读写任务、检查版本号
5. 确认无误后 docker image prune 清理旧镜像

问题 8：升级后页面异常 / 接口报错

三个常见原因：浏览器缓存了旧前端资源（强制刷新 / 清缓存）；新版要求执行数据库迁移（看镜像文档，通常容器启动时自动执行）；环境变量名在新版有变更（对照部署文档的变更日志）。

五、一页速查表

结语

自托管的运维负担，实际就是备份、升级、端口这三件事的纪律化：数据有挂载、备份有异地、升级先备份。把这三条变成肌肉记忆，自托管待办应用会是你用过最安心的软件之一。部署入口参见PriTime 部署文档，或在官网了解开源详情。