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

# 构建并启动
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

常用命令

docker compose ps                    # 状态
docker compose logs -f zhimingge   # 日志
docker compose restart zhimingge     # 重启
docker compose down                  # 停止并删除容器
docker compose up -d --build         # 重建并启动

环境变量

通过 .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
PORT	否	容器内 3130

防火墙

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 存在

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