Add Docker deployment as the recommended production setup.

Include Dockerfile, docker-compose on port 3130, npm mirror config, deploy scripts, and DOCKER.md; keep PM2 docs as fallback.

Co-authored-by: Cursor <cursoragent@cursor.com>

docs/DEPLOY.md

@@ -1,7 +1,9 @@
-# 知命阁（zhimingge）Ubuntu 部署文档
+# 知命阁（zhimingge）Ubuntu 部署文档（PM2 备选）
 
 > 仓库：[https://git.bz121.com/dekun/zhimingge.git](https://git.bz121.com/dekun/zhimingge.git)
 
+> **推荐改用 Docker 部署**，见 [DOCKER.md](./DOCKER.md)。本文档保留 PM2 手动部署说明。
+
 本文档说明在 **Ubuntu 服务器**上使用 **root 用户**、**PM2** 将知命阁部署到 **`/opt/zhimingge`** 的完整流程。
 
 ---
@@ -391,6 +393,37 @@ pm2 logs zhimingge --lines 100
 | 构建 OOM | 内存不足 | 增加 swap 或升级内存 |
 | 流式输出中断 | Nginx 缓冲 | 设置 `proxy_buffering off` |
 | Git pull 失败 | 凭据过期 | 重新配置 Token 或 SSH |
+| `npm install` 长时间无输出 | 官方 npm 源慢 / 下载 `@next/swc` 等大包 | 见下方「npm 安装卡住」 |
+
+### npm 安装卡住
+
+国内服务器访问 `registry.npmjs.org` 常极慢，表现为 `npm install` 只有转圈、无进度。
+
+**1. 先 Ctrl+C 中断，改用国内镜像：**
+
+```bash
+cd /opt/zhimingge
+npm config set registry https://registry.npmmirror.com
+npm config set fetch-timeout 600000
+npm install --no-audit --no-fund --loglevel=info
+```
+
+项目根目录已包含 `.npmrc`（`git pull` 后自动生效），也可直接：
+
+```bash
+git pull origin main
+npm install --loglevel=info
+```
+
+**2. 看卡在哪一步**（可选）：
+
+```bash
+npm install --loglevel=verbose 2>&1 | tee /tmp/npm-install.log
+```
+
+若长时间停在 `@next/swc-*` 或 `sharp`，属正常现象，多等几分钟；超 10 分钟仍无进展再换镜像重试。
+
+**3. 内存不足时**（构建阶段 OOM）见下方 Swap 配置。
 
 ### 构建内存不足时增加 Swap
 

docs/DOCKER.md

@@ -0,0 +1,96 @@
+# 知命阁 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
+
+# 构建并启动
+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
+```
+
+## 常用命令
+
+```bash
+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 |
+
+## 防火墙
+
+```bash
+ufw allow 3130
+# 或使用 Nginx 反代 80/443 → 3130
+```
+
+## 从 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` |
+| 卦辞 404 | 确认镜像内 `/app/content/zhouyi/docs` 存在 |
+
+构建在镜像内完成，**无需**在宿主机单独 `npm install` / `npm run build`。