# 圣鸡教廷·AI辩经馆部署方案

## 推荐上线架构

推荐采用单域名部署：

- 浏览器访问 `https://your-domain.com`
- `Nginx` 同时托管静态前端和反向代理 Node AI 适配层
- 前端静态资源：
  - `index.html`
  - `runtime-config.js`
  - `The_Clockmaker_s_Prayer.mp3`
  - 可选 `offline-preview.html`
- 后端适配层：
  - `server/server.js`
- 上游模型：
  - 任意 OpenAI-compatible 接口
  - 推荐优先 `responses` 风格

这样做的优点：

- 前后端同域，避免跨域问题
- API Key 只放在后端，不暴露给浏览器
- 纯 HTML 主站无需构建
- SSE 流式输出可直接穿透

## 当前文件整理后的角色

- `index.html`
  - 正式主站页面
- `runtime-config.js`
  - 运行时接口配置
  - 本地 `file://` 打开时默认连 `http://127.0.0.1:8788/v1/responses`
  - 正式 HTTPS 环境下默认连同域 `/v1/responses`
- `offline-preview.html`
  - 纯离线预览版
- `server/server.js`
  - 零依赖 Node AI 适配层
- `server/example.env.sh`
  - 本地 shell 启动示例
- `deploy/holy-chicken-ai.service`
  - `systemd` 服务模板
- `deploy/nginx.holy-chicken.conf`
  - Nginx 站点模板
- `deploy/holy-chicken-ai.env.example`
  - 生产环境变量模板
- `CHICKEN_DOCTRINE_REFERENCE.md`
  - 教义与人格约束参考

## 生产环境建议

- 系统：Ubuntu 22.04 或 24.04
- Node.js：20 或更高
- Nginx：1.22 或更高
- 域名：1 个即可
- SSL：Let's Encrypt / Certbot

## 一、上传项目文件

推荐服务器目录：

```bash
sudo mkdir -p /opt/holy-chicken-ai-debate-hall/server
sudo mkdir -p /var/www/holy-chicken-ai-debate-hall
sudo mkdir -p /etc/holy-chicken-ai
```

上传后建议目录结构：

```text
/opt/holy-chicken-ai-debate-hall/server
  package.json
  server.js

/var/www/holy-chicken-ai-debate-hall
  index.html
  runtime-config.js
  The_Clockmaker_s_Prayer.mp3
  offline-preview.html
```

## 二、配置前端运行时地址

正式环境下，推荐保持同域调用：

- 前端页面：`https://your-domain.com`
- API 接口：`https://your-domain.com/v1/responses`

默认 `runtime-config.js` 已经支持这套逻辑：

- 本地打开文件：走 `http://127.0.0.1:8788/v1/responses`
- 线上 HTTPS：走 `/v1/responses`

如果你需要单独 API 域名，可以直接修改 [runtime-config.js](/Users/adonisdc/Documents/New%20project/holy-chicken-ai-debate-hall/runtime-config.js) 中的默认地址逻辑。

## 三、配置后端环境变量

复制模板：

```bash
sudo cp /opt/holy-chicken-ai-debate-hall/deploy/holy-chicken-ai.env.example /etc/holy-chicken-ai/holy-chicken-ai.env
sudo nano /etc/holy-chicken-ai/holy-chicken-ai.env
```

最关键的变量：

- `UPSTREAM_BASE_URL`
  - 你的模型接口根地址，如 `https://api.provider.com/v1`
- `UPSTREAM_API_KEY`
  - 上游模型密钥
- `UPSTREAM_MODEL`
  - 模型名
- `UPSTREAM_API_STYLE`
  - 若你的接口兼容 OpenAI Responses，设为 `responses`
  - 若只兼容 Chat Completions，设为 `chat`
  - 不确定时可设为 `auto`
- `CORS_ORIGIN`
  - 推荐写成你的正式域名，如 `https://your-domain.com`
- `APP_TOKEN`
  - 如果前后端同域且只通过 Nginx 内部代理访问，可以留空
  - 如果你允许跨域直接访问后端，建议设置 Bearer Token

## 四、启动 Node 后端

因为本项目后端零依赖，通常不需要安装额外 npm 包：

```bash
cd /opt/holy-chicken-ai-debate-hall/server
node server.js
```

先手动测试健康检查：

```bash
curl http://127.0.0.1:8788/health
```

如果返回健康状态，再挂到 `systemd`。

## 五、配置 systemd 常驻服务

复制服务文件：

```bash
sudo cp /opt/holy-chicken-ai-debate-hall/deploy/holy-chicken-ai.service /etc/systemd/system/holy-chicken-ai.service
sudo systemctl daemon-reload
sudo systemctl enable --now holy-chicken-ai.service
```

查看状态：

```bash
sudo systemctl status holy-chicken-ai.service
journalctl -u holy-chicken-ai.service -f
```

## 六、配置 Nginx

复制模板：

```bash
sudo cp /opt/holy-chicken-ai-debate-hall/deploy/nginx.holy-chicken.conf /etc/nginx/sites-available/holy-chicken-ai
sudo ln -s /etc/nginx/sites-available/holy-chicken-ai /etc/nginx/sites-enabled/holy-chicken-ai
```

需要修改的两处：

- `server_name your-domain.com;`
- `root /var/www/holy-chicken-ai-debate-hall;`

检查并重载：

```bash
sudo nginx -t
sudo systemctl reload nginx
```

## 七、签发 HTTPS

```bash
sudo apt update
sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com
```

签发完成后，再次检查：

```bash
curl https://your-domain.com/health
```

## 八、联调验证

### 1. 验证静态页

浏览器打开：

- `https://your-domain.com`

确认：

- 主页面正常加载
- 音乐资源可访问
- 3D 场景正常显示

### 2. 验证接口

```bash
curl -X POST https://your-domain.com/v1/responses \
  -H 'Content-Type: application/json' \
  --data '{
    "instructions": "保持教皇鸡人格",
    "input": [
      {
        "type": "message",
        "role": "user",
        "content": "鸡为何高于人类？"
      }
    ],
    "stream": false,
    "store": false,
    "session_id": "deploy-check"
  }'
```

确认：

- 有 JSON 返回
- 文案符合教皇鸡人格
- 浏览器前端也能正常出字

### 3. 验证流式输出

检查浏览器 Network 面板：

- `POST /v1/responses`
- `Content-Type: text/event-stream`
- 页面能边生成边显示

## 九、推荐正式上线策略

推荐分三步：

1. 本地联调
   - 浏览器打开本地 `index.html`
   - 本地 Node 监听 `8788`
2. 预发布环境
   - 用子域名如 `staging.your-domain.com`
   - 接真模型接口
   - 测试音乐、3D、流式、异常提示
3. 生产环境
   - 切主域名
   - 配 HTTPS
   - 开启日志和备份模型

## 十、安全建议

- 不要把真实上游 API Key 写进前端或仓库公开文件
- 正式环境不要继续使用 `CORS_ORIGIN="*"`
- 如果需要跨域调用，启用 `APP_TOKEN`
- 建议配置主备上游：
  - `UPSTREAM_*`
  - `FALLBACK_UPSTREAM_*`
- 建议把服务器访问日志和 `journalctl` 日志保留至少 7 天

## 十一、最简可行上线方案

如果你想最快上线，直接采用下面这一套：

1. 一台 Ubuntu 云服务器
2. 一个域名 `your-domain.com`
3. 静态文件放 `/var/www/holy-chicken-ai-debate-hall`
4. Node 后端跑在 `127.0.0.1:8788`
5. Nginx 同时服务静态页和 `/v1/responses`
6. 上游模型用你现有 OpenAI-compatible 提供商

这就是当前项目最稳、最省事、最适合这套纯 HTML 前端的生产方案。
