diff --git a/README.md b/README.md index d0f2357..f9bc9a4 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,8 @@ - [产品说明文档（SPEC）](./docs/SPEC.md) — 功能规格、架构、实施分期 - [Docker 部署文档（DOCKER）](./docs/DOCKER.md) — **推荐** 生产部署 +- [宝塔反代与部署（BAOTA）](./docs/BAOTA.md) — **宝塔面板** 域名 + HTTPS + AI 流式反代 +- [Nginx 反代参考（NGINX）](./docs/NGINX.md) — 手写 Nginx 配置 - [Ubuntu PM2 部署文档（DEPLOY）](./docs/DEPLOY.md) — 备选方案 ## 环境变量 @@ -54,6 +56,8 @@ docker compose up -d 日常更新：`bash scripts/docker-deploy.sh` +绑定域名（宝塔/Nginx）及 AI 流式反代配置见 [docs/BAOTA.md](./docs/BAOTA.md)。 + ### PM2 部署（备选） 见 [docs/DEPLOY.md](./docs/DEPLOY.md)。 diff --git a/docs/BAOTA.md b/docs/BAOTA.md new file mode 100644 index 0000000..5d66d76 --- /dev/null +++ b/docs/BAOTA.md @@ -0,0 +1,225 @@ +# 宝塔面板部署与反向代理 + +> 适用场景：知命阁已通过 **Docker** 跑在 `127.0.0.1:3130`，再用 **宝塔（BT Panel）** 绑定域名（如 `gate.hyf2.cc`）对外提供 HTTPS 访问。 + +--- + +## 一、架构说明 + +``` +浏览器 → HTTPS (443) → 宝塔 Nginx → http://127.0.0.1:3130 → Docker 容器 zhimingge +``` + +- 应用本身监听 **3130**，不直接暴露公网也可（仅 Nginx 反代）。 +- AI 解读走 **`POST /api/ai`** 流式接口，Nginx **必须关闭缓冲**，否则页面上会一直空白。 +- 浏览器请求的是 **域名**，`curl 127.0.0.1:3130` 能通不代表域名一定通，两处都要测。 + +--- + +## 二、Docker 部署（首次 / 更新） + +### 2.1 首次部署 + +```bash +cd /opt +git clone https://git.bz121.com/dekun/zhimingge.git zhimingge +cd /opt/zhimingge + +cp .env.example .env.local +nano .env.local # 填写 OPENAI_API_KEY 等 +chmod 600 .env.local + +docker compose build --no-cache +docker compose up -d +``` + +### 2.2 环境变量（`.env.local`） + +```env +OPENAI_API_KEY=sk-你的密钥 +OPENAI_BASE_URL=https://op.bz121.com/v1 +OPENAI_MODEL=huihui_ai/gemma-4-abliterated:e4b +``` + +| 变量 | 必填 | 说明 | +|------|------|------| +| `OPENAI_API_KEY` | 是 | AI 接口密钥 | +| `OPENAI_BASE_URL` | 否 | 与 `OPENAI_API_BASE` 二选一，默认 `https://op.bz121.com/v1` | +| `OPENAI_MODEL` | 否 | 默认 `huihui_ai/gemma-4-abliterated:e4b` | + +### 2.3 日常更新 + +```bash +cd /opt/zhimingge +bash scripts/docker-deploy.sh +``` + +或手动： + +```bash +git pull origin main +docker compose build --no-cache +docker compose up -d --force-recreate +``` + +### 2.4 确认容器正常 + +```bash +docker compose ps +docker exec zhimingge printenv OPENAI_API_KEY | head -c 8 # 应看到 sk- 开头 +curl -s http://127.0.0.1:3130/api/health +# {"ok":true,"service":"zhimingge","apiAi":true,...} +``` + +更多 Docker 说明见 [DOCKER.md](./DOCKER.md)。 + +--- + +## 三、宝塔添加站点与反向代理 + +### 3.1 添加网站 + +1. 宝塔 → **网站** → **添加站点** +2. 域名填：`gate.hyf2.cc`（换成你的域名） +3. PHP 选 **纯静态** 或随意（实际由反代到 3130） +4. 按需申请 **SSL**（Let's Encrypt） + +### 3.2 配置反向代理 + +**方式 A（推荐）**：网站 → 选中站点 → **反向代理** → **添加反向代理** + +- 代理名称：`zhimingge` +- 目标 URL：`http://127.0.0.1:3130` +- 发送域名：`$host`（不要填 `127.0.0.1`） + +添加后点击 **配置文件**，找到 `#PROXY-START/` … `#PROXY-END/` 整段，**替换为下方完整配置**。 + +**方式 B**：网站 → **设置** → **配置文件**，在 `server { ... }` 内手动加入 `location`。 + +--- + +## 四、宝塔反代配置（完整可复制） + +将站点配置中 `#PROXY-START/` 到 `#PROXY-END/` **整段替换**为： + +```nginx +#PROXY-START/ + +location ^~ / +{ + proxy_pass http://127.0.0.1:3130; + proxy_http_version 1.1; + + # 必须用真实域名，不要用 127.0.0.1 + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_set_header REMOTE-HOST $remote_addr; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $connection_upgrade; + + # AI 流式输出：必须关闭缓冲 + proxy_buffering off; + proxy_cache off; + proxy_read_timeout 300s; + proxy_send_timeout 300s; + chunked_transfer_encoding on; + + add_header X-Cache $upstream_cache_status; + + # 静态资源短缓存 + set $static_filelkzjrLn7 0; + if ( $uri ~* "\.(gif|png|jpg|css|js|woff|woff2)$" ) + { + set $static_filelkzjrLn7 1; + expires 1m; + } + if ( $static_filelkzjrLn7 = 0 ) + { + add_header Cache-Control no-cache; + } +} + +#PROXY-END/ +``` + +### 4.1 与默认宝塔配置的差异（必改项） + +| 原配置（错误） | 应改为 | 原因 | +|----------------|--------|------| +| `proxy_set_header Host 127.0.0.1;` | `proxy_set_header Host $host;` | Next.js 需要正确 Host，否则路由 / API 异常 | +| （无） | `proxy_set_header X-Forwarded-Proto $scheme;` | HTTPS 站点识别协议 | +| （无） | `proxy_buffering off;` | **AI 流式必须**，否则浏览器收不到逐字输出 | +| （无） | `proxy_read_timeout 300s;` | 模型生成较慢时不超时 | + +保存后在宝塔点击 **重载配置**，或 SSH 执行： + +```bash +nginx -t && systemctl reload nginx +``` + +### 4.2 注意 + +- 只保留 **一层** 到 3130 的反代，避免同一站点重复添加多个冲突的 `location /`。 +- 若曾用 **PM2** 占 3130，需先停掉：`pm2 stop zhimingge; pm2 delete zhimingge` +- 防火墙可只开放 80/443，**不必**对公网开放 3130。 + +--- + +## 五、验证（本地 + 域名都要测） + +### 5.1 健康检查 + +```bash +# 直连容器（应返回 JSON） +curl -s http://127.0.0.1:3130/api/health + +# 经域名（应同样返回 JSON；若 HTML/404 则是 Nginx 问题） +curl -s https://gate.hyf2.cc/api/health +``` + +期望输出示例： + +```json +{"ok":true,"service":"zhimingge","apiAi":true,"build":"dba0245+"} +``` + +### 5.2 AI 流式接口 + +```bash +curl -N -X POST https://gate.hyf2.cc/api/ai \ + -H "Content-Type: application/json" \ + -d '{"mode":"bazi","payload":{"input":{"date":"1990-01-01","time":"12:00","gender":"male","longitude":120},"question":"测试","birthPlaceName":"上海市"}}' +``` + +应看到 **中文内容逐字输出**，而不是 HTML 404 页面。 + +### 5.3 六爻 AI 解读（页面） + +1. 打开 `https://gate.hyf2.cc/liuyao` +2. 填写问事、地域、完成起卦 +3. 点击 **AI 解读** +4. 结果区应出现流式文字；加载中会显示「AI 分析中...」 + +--- + +## 六、常见问题 + +| 现象 | 可能原因 | 处理 | +|------|----------|------| +| `curl 127.0.0.1:3130/api/health` 正常，域名 404 | Nginx 未反代或未重载 | 检查宝塔反代配置，`nginx -t && systemctl reload nginx` | +| 域名返回 HTML 404 | 反代目标错误或旧容器 | 确认 `proxy_pass http://127.0.0.1:3130`，`docker compose ps` | +| 页面 AI 一直空白 | `proxy_buffering` 未关 | 按第四节加上 `proxy_buffering off` | +| 页面 AI 报错「接口未到达后端」 | `Host` 设为 127.0.0.1 | 改为 `Host $host` | +| AI 很快超时 | 读超时太短 | 设置 `proxy_read_timeout 300s` | +| 构建后仍无 `/api/ai` | 镜像未更新 | `git pull` + `docker compose build --no-cache` + `up -d --force-recreate` | +| 容器内无密钥 | `.env.local` 未挂载 | 检查 `docker-compose.yml` 的 `env_file`，`docker exec zhimingge printenv OPENAI_API_KEY` | + +--- + +## 七、相关文档 + +- [DOCKER.md](./DOCKER.md) — Docker 构建、环境变量、排错 +- [NGINX.md](./NGINX.md) — 非宝塔、手写 Nginx 配置参考 +- [DEPLOY.md](./DEPLOY.md) — PM2 备选部署 diff --git a/docs/DOCKER.md b/docs/DOCKER.md index 87921da..98ba43b 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -72,9 +72,11 @@ docker compose up -d --build # 重建并启动 ```bash ufw allow 3130 -# 或使用 Nginx 反代 80/443 → 3130 +# 或使用 Nginx / 宝塔 反代 80/443 → 3130（推荐，不必对公网开放 3130） ``` +域名与 AI 流式反代完整说明见 [BAOTA.md](./BAOTA.md)。 + ## 从 PM2 迁移 ```bash @@ -90,7 +92,8 @@ docker compose up -d --build |------|------| | 构建慢 / 超时 | Dockerfile 使用 `.npmrc` 国内镜像；重试 `docker compose build` | | 容器反复重启 | `docker compose logs zhimingge` 查看报错 | -| AI 失败 | 检查 `.env.local` 中 `OPENAI_API_KEY` | +| 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` 存在 | 构建在镜像内完成，**无需**在宿主机单独 `npm install` / `npm run build`。 diff --git a/docs/NGINX.md b/docs/NGINX.md index 3f0de1d..8096caf 100644 --- a/docs/NGINX.md +++ b/docs/NGINX.md @@ -1,4 +1,6 @@ -# Nginx 反代 + AI 流式输出 +# Nginx 反向代理（手写配置） + +> 若使用 **宝塔面板**，请直接看 **[BAOTA.md](./BAOTA.md)**，内含完整 `#PROXY-START/` 配置与操作步骤。 浏览器访问 `https://你的域名/api/ai` 必须能到达 Next.js（3130），且**关闭缓冲**，否则页面上 AI 解读会一直空白或等到超时。 @@ -14,9 +16,9 @@ curl -s http://127.0.0.1:3130/api/health curl -s https://gate.hyf2.cc/api/health ``` -若本地成功、域名 404 或返回 HTML，说明 Nginx 未正确反代 `/api/`。 +若本地成功、域名 404 或返回 HTML，说明 Nginx 未正确反代。 -## 2. 推荐配置 +## 2. 推荐配置（非宝塔） ```nginx server { @@ -49,7 +51,7 @@ server { nginx -t && systemctl reload nginx ``` -## 3. 浏览器测试 +## 3. AI 接口测试 ```bash curl -N -X POST https://gate.hyf2.cc/api/ai \