dekun
276 lines
7.3 KiB
Markdown
276 lines
7.3 KiB
Markdown
# 知命阁 Docker 部署
|
||
|
||
> 推荐生产部署方式，端口 **3130**
|
||
|
||
## 前置条件
|
||
|
||
```bash
|
||
# Ubuntu 安装 Docker
|
||
apt update
|
||
apt install -y docker.io docker-compose-v2
|
||
systemctl enable docker --now
|
||
docker --version
|
||
docker compose version
|
||
```
|
||
|
||
## 首次部署
|
||
|
||
```bash
|
||
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`
|
||
|
||
## 日常更新
|
||
|
||
```bash
|
||
cd /opt/zhimingge
|
||
bash scripts/docker-deploy.sh
|
||
```
|
||
|
||
或手动：
|
||
|
||
```bash
|
||
git pull origin main
|
||
docker compose build
|
||
docker compose up -d
|
||
```
|
||
|
||
## 修改环境变量后重启
|
||
|
||
环境变量写在项目根目录的 `.env.local` 中，由 `docker-compose.yml` 的 `env_file` 注入容器。**变量在创建容器时读取**，改 env 后必须**重建容器**才会生效。
|
||
|
||
### 服务器（Docker）
|
||
|
||
```bash
|
||
cd /opt/zhimingge
|
||
nano .env.local # 改完保存
|
||
docker compose up -d --force-recreate
|
||
```
|
||
|
||
确认服务正常：
|
||
|
||
```bash
|
||
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`。
|
||
|
||
### 本地开发
|
||
|
||
```bash
|
||
# 改 .env.local 后，Ctrl+C 停掉 dev 进程，再重新启动
|
||
npm run dev
|
||
```
|
||
|
||
Next.js 只在启动时读取 env，热更新不会自动加载新变量。
|
||
|
||
### PM2 部署（旧方式）
|
||
|
||
若仍使用 PM2 而非 Docker：
|
||
|
||
```bash
|
||
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 挂载到容器），按登录用户名分文件；八字/综合测算会保存出生信息与四柱排盘。
|
||
|
||
验证容器内是否生效（示例）：
|
||
|
||
```bash
|
||
docker exec zhimingge printenv OPENAI_API_KEY
|
||
docker exec zhimingge printenv AUTH_USERNAME
|
||
```
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
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>` 悬空镜像**，长期不清理会占满磁盘。
|
||
|
||
### 查看占用
|
||
|
||
```bash
|
||
docker system df # 汇总：镜像 / 容器 / 构建缓存各占多少
|
||
docker images # 列出所有镜像
|
||
docker images zhimingge # 仅知命阁（通常只有 zhimingge:latest）
|
||
```
|
||
|
||
### 推荐：安全清理（不影响正在运行的容器）
|
||
|
||
在项目目录执行：
|
||
|
||
```bash
|
||
cd /opt/zhimingge
|
||
bash scripts/docker-prune.sh
|
||
```
|
||
|
||
等价手动命令：
|
||
|
||
```bash
|
||
docker image prune -f # 删除悬空镜像 <none>
|
||
docker builder prune -f # 删除构建缓存
|
||
```
|
||
|
||
### 深度清理：删除所有未使用的镜像
|
||
|
||
**不会删除**正在被 `zhimingge` 容器使用的 `zhimingge:latest`，但会删掉其他项目的闲置镜像：
|
||
|
||
```bash
|
||
bash scripts/docker-prune.sh --all
|
||
# 或
|
||
docker image prune -a -f
|
||
```
|
||
|
||
### 删除指定镜像
|
||
|
||
```bash
|
||
# 先确认没有容器在用（STATE 应为 Up）
|
||
docker compose ps
|
||
|
||
# 按镜像 ID 删除（把 abc123 换成 docker images 里的 IMAGE ID）
|
||
docker rmi abc123
|
||
|
||
# 强制删除（仅当该镜像未被任何容器使用时）
|
||
docker rmi -f abc123
|
||
```
|
||
|
||
**不要**在容器仍在运行时执行 `docker rmi zhimingge:latest`，会失败或导致异常。
|
||
|
||
### 停止服务并删除本项目镜像
|
||
|
||
仅当需要完全卸载、或镜像损坏需从零重建时：
|
||
|
||
```bash
|
||
cd /opt/zhimingge
|
||
docker compose down # 停止并删除容器
|
||
docker rmi zhimingge:latest # 删除知命阁镜像
|
||
docker compose build --no-cache
|
||
docker compose up -d
|
||
```
|
||
|
||
或使用 Compose 自带选项（停止容器并删除**本项目构建的**镜像）：
|
||
|
||
```bash
|
||
docker compose down --rmi local
|
||
```
|
||
|
||
### 一键释放最多空间（慎用）
|
||
|
||
会删除**所有**未使用的镜像、容器、网络（同一台机器上其他 Docker 项目也会受影响）：
|
||
|
||
```bash
|
||
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 |
|
||
|
||
### 排错：清理后服务起不来
|
||
|
||
```bash
|
||
cd /opt/zhimingge
|
||
docker compose build --no-cache
|
||
docker compose up -d --force-recreate
|
||
curl -s http://127.0.0.1:3130/api/health
|
||
```
|
||
|
||
## 防火墙
|
||
|
||
```bash
|
||
ufw allow 3130
|
||
# 或使用 Nginx / 宝塔 反代 80/443 → 3130（推荐，不必对公网开放 3130）
|
||
```
|
||
|
||
域名与 AI 流式反代完整说明见 [BAOTA.md](./BAOTA.md)。
|
||
|
||
## PWA 安装
|
||
|
||
应用已支持添加到主屏幕（手机 / 桌面 Chrome、Edge 等）：
|
||
|
||
- 首次访问会提示「安装知命阁」
|
||
- iOS Safari：分享 → 添加到主屏幕
|
||
- 需 HTTPS 访问（经宝塔域名）
|
||
|
||
## 从 PM2 迁移
|
||
|
||
```bash
|
||
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](./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`。
|