zhimingge/docs/BAOTA.md

宝塔面板部署与反向代理

适用场景：知命阁已通过 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 首次部署

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）

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 日常更新

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

或手动：

git pull origin main
docker compose build --no-cache
docker compose up -d --force-recreate

2.4 确认容器正常

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（含镜像清理）。

2.5 清理无用 Docker 镜像

多次 build --no-cache 后磁盘会堆积旧层，建议定期执行：

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

深度清理（删除所有未被容器使用的镜像）：

bash scripts/docker-prune.sh --all

详细说明见 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/ 整段替换为：

#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 执行：

nginx -t && systemctl reload nginx

4.2 注意

• 只保留 一层 到 3130 的反代，避免同一站点重复添加多个冲突的 location /。
• 若曾用 PM2 占 3130，需先停掉：pm2 stop zhimingge; pm2 delete zhimingge
• 防火墙可只开放 80/443，不必对公网开放 3130。

---

五、验证（本地 + 域名都要测）

5.1 健康检查

# 直连容器（应返回 JSON）
curl -s http://127.0.0.1:3130/api/health

# 经域名（应同样返回 JSON；若 HTML/404 则是 Nginx 问题）
curl -s https://gate.hyf2.cc/api/health

期望输出示例：

{"ok":true,"service":"zhimingge","apiAi":true,"build":"dba0245+"}

5.2 AI 流式接口

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 构建、环境变量、排错
• NGINX.md — 非宝塔、手写 Nginx 配置参考
• DEPLOY.md — PM2 备选部署