wiki_crawler/docs/docker.md

Wiki Crawler Backend 部署操作手册

核心配置信息 (每次只需修改这里)

在执行命令前，请先确定本次发布的 版本号。

字段	当前值 (示例)	说明	每次要改吗？
Version	v1.0.4	镜像的版本标签 (Tag)	是 (必须改)
Image Name	wiki-crawl-backend	镜像/容器的名字	否 (固定)
Namespace	qg-demo	阿里云命名空间	否 (固定)
Registry	crpi-1rwd6fvain6t49g2...	阿里云仓库地址	否 (固定)

---

第一阶段：本地电脑 (Windows) - 打包与上传

打开 PowerShell 或 CMD，进入项目根目录。

1. 构建镜像 (Build)

修改命令最后的版本号 v1.0.4

docker build -t crpi-1rwd6fvain6t49g2.cn-hangzhou.personal.cr.aliyuncs.com/qg-demo/wiki-crawl-backend:v1.0.4 .

2. 推送镜像 (Push)

修改命令最后的版本号 v1.0.4

docker push crpi-1rwd6fvain6t49g2.cn-hangzhou.personal.cr.aliyuncs.com/qg-demo/wiki-crawl-backend:v1.0.4

成功标准： 看到进度条走完，且最后显示 Pushed。

---

第二阶段：云服务器 (Linux) - 部署更新

使用 SSH 登录阿里云服务器，按顺序执行。

1. 拉取新镜像 (Pull)

修改命令最后的版本号 v1.0.4

docker pull crpi-1rwd6fvain6t49g2.cn-hangzhou.personal.cr.aliyuncs.com/qg-demo/wiki-crawl-backend:v1.0.4

2. 停止并删除旧容器

这一步是为了释放端口，不会删除镜像文件

docker stop wiki-crawl-backend
docker rm wiki-crawl-backend

3. 启动新容器 (Run) - 关键步骤

修改命令最后的版本号 v1.0.4

codeBash

docker run -d --name wiki-crawl-backend \
  -e PYTHONUNBUFFERED=1 \
  -p 80:8000 \
  crpi-1rwd6fvain6t49g2.cn-hangzhou.personal.cr.aliyuncs.com/qg-demo/wiki-crawl-backend:v1.0.4

4. 验证与日志查看

codeBash

# 查看容器状态 (STATUS 应该是 Up)
docker ps

# 查看实时日志 (按 Ctrl+C 退出)
docker logs -f wiki-crawl-backend

---

第三阶段：清理工作 (可选)

为了防止服务器硬盘被旧版本的镜像塞满，建议定期执行清理。

codeBash

# 删除所有“未被使用”的旧镜像
docker image prune -a -f

---

附录：命令参数详解 (小白必读)

在 docker run 命令中，各个参数的含义如下：

1. -d (Detached)

• 含义： 后台运行。
• 作用： 容器启动后会默默在后台跑，不会占用你的黑窗口。如果不加这个，你一关 SSH 窗口，服务就停了。

2. --name wiki-crawl-backend

• 含义： 给容器起个名字。
• 作用： 有了名字，以后你要停止它、重启它、看日志，直接叫它的名字就行（比如 docker stop wiki-crawl-backend），不用去查那串随机的容器 ID。

3. -e PYTHONUNBUFFERED=1

• 含义： 设置环境变量 (Environment Variable)。

• 作用： 这是一个 Python 专用的设置。意思是“不要缓存输出”。

  • 如果不加：Python 会把日志憋在肚子里，攒够了一坨才吐出来，导致你用 docker logs 只能看到几分钟前的日志。
  • 加了：日志实时打印，报错立刻能看到。

4. -p 80:8000 (Port Mapping)

• 含义： 端口映射。格式是 宿主机端口:容器内部端口。

• 解析：

  • 80 (左边)：这是阿里云服务器对外的门牌号。用户访问 http://1.2.3.4 时，默认就是找 80 端口。
  • 8000 (右边)：这是你 Python 代码 (FastAPI/Uvicorn) 实际监听的端口。
  • 作用： 把服务器大门 (80) 接到的客人，领到 Python 小房间 (8000) 去。

5. 那个超长的 URL

crpi-1rwd6fvain6t49g2.cn-hangzhou.personal.cr.aliyuncs.com/qg-demo/wiki-crawl-backend:v1.0.4

• Registry (仓库地址): crpi-1rwd...aliyuncs.com -> 你的专属阿里云仓库服务器。
• Namespace (命名空间): qg-demo -> 你在仓库里划出的个人地盘。
• Image Name (镜像名): wiki-crawl-backend -> 这个项目的名字。
• Tag (标签): v1.0.4 -> 相当于软件的版本号。如果不写 Tag，默认就是 latest。生产环境强烈建议写明确的版本号，方便回滚（比如 1.0.3 挂了，你可以立马用 1.0.2 启动）。