| name | rebuild |
| description | Rebuild the Keeper_CoC-TRPG Docker image and push to NyaaDockerHUB private registry. Use this whenever the project needs a Docker rebuild (e.g., after Dockerfile, docker-compose.yml, server.ts, or any source change that affects the bundled image). Runs rebuild.py which builds, tags, pushes to private registry, and cleans old tags. |
rebuild
本项目需要重新编译 Docker 镜像并推送到 NyaaDockerHUB 时调用此 skill。
触发场景
- 用户明确要求"重新编译"、"重建镜像"、"rebuild"。
- 改动了
Dockerfile、docker-compose.yml、.dockerignore 等容器构建相关文件。
- 改动了
server.ts / src/** / vite.config.ts / package.json 等会影响镜像内构建产物或 Node 依赖的源码 / 配置。
- 通过
/rebuild 显式调用。
执行
统一使用 Python 脚本（跨平台，无执行策略问题）：
python rebuild.py
如需全量重建（跳过层缓存）：
python rebuild.py --no-cache
仅本地构建不推送（离线/调试）：
python rebuild.py --skip-push
脚本流程
- 读取
.env 获取 PRIVATE_DOCKER_REGISTRY_HOST 和 URL
git rev-parse --short=7 HEAD 获取版本标签- Registry 健康检查（
/v2/）
docker build 双标签：<registry>/keeper-coc-trpg:<sha> + :latestdocker push 双标签（各重试 3 次，间隔 2 秒）- Registry HTTP API 清理旧 tag（仅保留当前 SHA 和 latest）
- 本地清理旧标签 + 悬空镜像
- 所有输出中仓库地址掩码为
<PRIVATE_REGISTRY>
macmini 部署
本地 rebuild.py 构建推送后，必须推送 .env 到 macmini 并重启容器：
scp .env U-MacMini-1:/root/DockerContainer/keeper-coc-trpg/.env && ssh U-MacMini-1 "export PATH=\$PATH:/snap/bin && cd /root/DockerContainer/keeper-coc-trpg && python3 restart.py"
.env 变更强制推送规则
只要 .env 中发生了影响 macmini 发布侧运行时行为的变更（如 NYAACHAT_MCP_URL、NYAAACOUNT_BASE_URL、NYAACHAT_MCP_TOKEN、PRIVATE_DOCKER_REGISTRY_* 等容器内通过 process.env 读取的变量），即使本次不需要 rebuild，也必须单独推送 .env 并重启 macmini 容器：
scp .env U-MacMini-1:/root/DockerContainer/keeper-coc-trpg/.env && ssh U-MacMini-1 "export PATH=\$PATH:/snap/bin && cd /root/DockerContainer/keeper-coc-trpg && python3 restart.py"
restart.py 流程：pull → down → up -d → prune → status。
关于缓存策略
脚本默认走 Docker 的层缓存（不带 --no-cache），原因：
- 多阶段 Dockerfile 第一层是
COPY package.json package-lock.json ./ + RUN npm ci。只要 lockfile 没变，这一层会命中缓存，秒级跳过；改 server.ts / src/** 时不需要重新拉 node_modules。
- Docker 的层指纹按指令文本 + 上游层 + 被 COPY 进来的文件内容来算，所以改源码自然会让对应层失效，不会出现"该重建却没重建"的情况。
什么时候确实需要全量重建：
- 怀疑 base image 自身有脏状态（很少见）。
- 改了 npm 镜像源 / 私有 registry 配置，担心旧缓存层里残留旧凭据。
- 排查"为什么改了 X 镜像里没生效"——先确认 Dockerfile 里这一层应该被 invalidate，再考虑
--no-cache。
需要时用 python rebuild.py --no-cache。
不要做的事
- 不要绕过脚本直接调用
docker compose build/up/down——使用脚本能保证流程一致。
- 不要随手
docker system prune -a —— 脚本里只清理 dangling 镜像，足够且安全。
- 不要使用已删除的
rebuild.ps1 / rebuild.sh（已迁移到 rebuild.py）。
- 不要将 registry 地址硬编码在任何文件中——始终从
.env 读取。
