zhimingge/docs/DOCKER.md

知命阁 Docker 部署

推荐生产部署方式，端口 3130

前置条件

# Ubuntu 安装 Docker
apt update
apt install -y docker.io docker-compose-v2
systemctl enable docker --now
docker --version
docker compose version

首次部署

cd /opt
git clone https://git.bz121.com/dekun/zhimingge.git zhimingge
cd /opt/zhimingge

# 环境变量（必填 OPENAI_API_KEY）
cp .env.example .env.local
nano .env.local
chmod 600 .env.local

# 测算历史持久化目录（挂载到容器）
mkdir -p data/history
chmod 755 data/history

# 构建并启动
docker compose build
docker compose up -d

访问：http://服务器IP:3130

日常更新

cd /opt/zhimingge
bash scripts/docker-deploy.sh

或手动：

git pull origin main
docker compose build
docker compose up -d

修改环境变量后重启

环境变量写在项目根目录的 .env.local 中，由 docker-compose.yml 的 env_file 注入容器。变量在创建容器时读取，改 env 后必须重建容器才会生效。

服务器（Docker）

cd /opt/zhimingge
nano .env.local          # 改完保存
docker compose up -d --force-recreate

确认服务正常：

curl http://127.0.0.1:3130/api/health
docker compose logs -f zhimingge   # 有问题时看日志

注意： docker compose restart zhimingge 只是重启旧容器，不会重新读取 .env.local。改 env 后请用 --force-recreate，不要用 restart。

改 env 不需要重新 build 镜像；只有代码变更时才需要 git pull + docker compose build + up -d。

本地开发

# 改 .env.local 后，Ctrl+C 停掉 dev 进程，再重新启动
npm run dev

Next.js 只在启动时读取 env，热更新不会自动加载新变量。

PM2 部署（旧方式）

若仍使用 PM2 而非 Docker：

cd /opt/zhimingge
nano .env.local
pm2 restart zhimingge

快速对照

场景	改 env 后怎么做
Docker 生产	docker compose up -d --force-recreate
本地 dev	停掉再 npm run dev
PM2	pm2 restart zhimingge

环境变量

通过 .env.local 注入容器（见 docker-compose.yml 的 env_file）：

变量	必填	说明
OPENAI_API_KEY	是	AI 接口密钥
OPENAI_BASE_URL	否	默认 https://op.bz121.com/v1
OPENAI_MODEL	否	默认 huihui_ai/gemma-4-abliterated:e4b
AUTH_USERNAME	否*	登录用户名；与下面两项同时配置后启用登录
AUTH_PASSWORD	否*	登录密码
AUTH_SESSION_SECRET	否*	会话签名密钥，建议 32 位以上随机字符串
HISTORY_DATA_DIR	否	测算历史 JSON 存储目录；Docker 默认 /app/data/history
PORT	否	容器内 3130

* 三项认证变量同时填写时，六爻/八字/综合测算与 AI 解读需登录；任一项留空则关闭登录限制。

测算历史保存在服务器 data/history/（Compose 挂载到容器），按登录用户名分文件；八字/综合测算会保存出生信息与四柱排盘。

验证容器内是否生效（示例）：

docker exec zhimingge printenv OPENAI_API_KEY
docker exec zhimingge printenv AUTH_USERNAME

常用命令

docker compose ps                    # 状态
docker compose logs -f zhimingge     # 日志
docker compose restart zhimingge     # 重启容器（不改 env 时用）
docker compose up -d --force-recreate  # 重建容器（改 .env.local 后用）
docker compose down                  # 停止并删除容器
docker compose up -d --build         # 重建镜像并启动（代码更新后用）

镜像清理

每次 docker compose build --no-cache 会在磁盘上留下旧层和 <none> 悬空镜像，长期不清理会占满磁盘。

查看占用

docker system df          # 汇总：镜像 / 容器 / 构建缓存各占多少
docker images             # 列出所有镜像
docker images zhimingge   # 仅知命阁（通常只有 zhimingge:latest）

推荐：安全清理（不影响正在运行的容器）

在项目目录执行：

cd /opt/zhimingge
bash scripts/docker-prune.sh

等价手动命令：

docker image prune -f      # 删除悬空镜像 <none>
docker builder prune -f    # 删除构建缓存

深度清理：删除所有未使用的镜像

不会删除正在被 zhimingge 容器使用的 zhimingge:latest，但会删掉其他项目的闲置镜像：

bash scripts/docker-prune.sh --all
# 或
docker image prune -a -f

删除指定镜像

# 先确认没有容器在用（STATE 应为 Up）
docker compose ps

# 按镜像 ID 删除（把 abc123 换成 docker images 里的 IMAGE ID）
docker rmi abc123

# 强制删除（仅当该镜像未被任何容器使用时）
docker rmi -f abc123

不要在容器仍在运行时执行 docker rmi zhimingge:latest，会失败或导致异常。

停止服务并删除本项目镜像

仅当需要完全卸载、或镜像损坏需从零重建时：

cd /opt/zhimingge
docker compose down          # 停止并删除容器
docker rmi zhimingge:latest  # 删除知命阁镜像
docker compose build --no-cache
docker compose up -d

或使用 Compose 自带选项（停止容器并删除本项目构建的镜像）：

docker compose down --rmi local

一键释放最多空间（慎用）

会删除所有未使用的镜像、容器、网络（同一台机器上其他 Docker 项目也会受影响）：

docker system prune -a -f

建议节奏

时机	操作
每次 docker compose build 之后	bash scripts/docker-prune.sh
磁盘紧张	bash scripts/docker-prune.sh --all
仅本项目重装	docker compose down --rmi local 后重新 build

排错：清理后服务起不来

cd /opt/zhimingge
docker compose build --no-cache
docker compose up -d --force-recreate
curl -s http://127.0.0.1:3130/api/health

防火墙

ufw allow 3130
# 或使用 Nginx / 宝塔 反代 80/443 → 3130（推荐，不必对公网开放 3130）

域名与 AI 流式反代完整说明见 BAOTA.md。

PWA 安装

应用已支持添加到主屏幕（手机 / 桌面 Chrome、Edge 等）：

• 首次访问会提示「安装知命阁」
• iOS Safari：分享 → 添加到主屏幕
• 需 HTTPS 访问（经宝塔域名）

从 PM2 迁移

pm2 stop zhimingge
pm2 delete zhimingge
cd /opt/zhimingge
docker compose up -d --build

排错

现象	处理
构建慢 / 超时	Dockerfile 使用 .npmrc 国内镜像；重试 docker compose build
容器反复重启	docker compose logs zhimingge 查看报错
AI 失败	检查 .env.local 中 OPENAI_API_KEY；docker exec zhimingge printenv OPENAI_API_KEY
页面 AI 空白、curl 本地正常	Nginx/宝塔未关缓冲或未反代域名，见 BAOTA.md
卦辞 404	确认镜像内 /app/content/zhouyi/docs 存在
测算历史保存失败	确认 data/history 存在且容器可写：mkdir -p data/history && chmod 777 data/history（或 chown 1001:1001）
磁盘满 / 镜像过多	bash scripts/docker-prune.sh，见 镜像清理

构建在镜像内完成，无需在宿主机单独 npm install / npm run build。