# 来客有方部署与维护手册

更新时间：2026-07-09

## 推荐路线

先把网页代码放入 GitHub 仓库，再绑定 Cloudflare Pages 自动部署。这样后续改页面、改模型配置、改 Worker API 网关都可以走 Git 提交和 PR，便于回滚、审查和多人维护。

## 当前工程结构建议

```text
lumoffice/
  prototype/                 # 静态前端站点，可直接部署到 Cloudflare Pages
    index.html
    assets/
    config/
      model-providers.json   # 常用主流模型配置表
      quota-management.json  # 额度管理表
      module-api-routes.json # 页面模块到 API/模型的调度映射
    docs/
  api-gateway/               # Cloudflare Worker API 网关骨架
    src/index.js
    wrangler.jsonc
    migrations/0001_initial.sql
```

## Cloudflare Pages 部署

Cloudflare 官方文档说明，静态 HTML 网站可以部署到 Pages，并可从 GitHub 仓库导入。静态站不需要构建时，构建命令可用 `exit 0`，输出目录填写站点文件目录。

推荐 Pages 配置：

```text
Production branch: main
Build command: exit 0
Build output directory: lumoffice/prototype
```

上线后把 API 网关地址配置到前端环境或配置文件中。当前原型先读取静态 JSON；正式产品建议改为从 `/api/model-configs`、`/api/quota-policies`、`/api/module-routes` 拉取。

## Cloudflare Worker API 网关

`lumoffice/api-gateway` 已准备：

- `wrangler.jsonc`
- D1 绑定占位：`DB`
- D1 初始化迁移：`migrations/0001_initial.sql`
- API：
  - `GET /api/health`
  - `GET /api/model-configs`
  - `GET /api/quota-policies`
  - `GET /api/module-routes`
  - `POST /api/route/resolve`
  - `POST /api/llm/chat`

部署前步骤：

```powershell
cd C:\Users\35160\Documents\Codex\lumoffice\api-gateway
npm install
npx wrangler d1 create laikeyoufang-prod-config
```

把返回的 `database_id` 写入 `wrangler.jsonc`。

```powershell
npm run db:migrate:remote
npx wrangler secret put OPENAI_API_KEY
npx wrangler secret put DEEPSEEK_API_KEY
npm run deploy
```

不要把 API key 写进 GitHub、JSON 配置或前端代码。只通过 `wrangler secret put` 或服务器环境变量注入。

RAG 接入时，把 `RAG_BASE_URL` 配成 Lumia Vault RAG 服务地址。 本地开发可用 `http://127.0.0.1:8001`；生产建议使用 VPS HTTPS 域名或 Cloudflare Tunnel 地址。Worker 的 `/api/knowledge/search` 会读取路由表中的 `knowledge.search` 策略，再代理到 `${RAG_BASE_URL}/rag/search`。

## 如果采用云服务器部署

适合以下情况：

- RAG 需要本地向量索引、文件导入、OCR、长任务。
- 需要定时任务、队列、浏览器自动化、平台发布适配器。
- 大模型调度逻辑变复杂，需要数据库事务、后台任务和更多观测。

推荐云服务器结构：

```text
Nginx/Caddy
  /              -> 静态前端 build 或 prototype
  /api/*         -> Node/FastAPI API Gateway
  /rag/*         -> RAG 服务
  /agents/ocr/*  -> OCR-Harness 服务
PostgreSQL       -> 账号、额度、审计、发布任务
Redis            -> 队列、限流、短期缓存
Object Storage   -> 图片/视频素材
PM2/systemd      -> 服务守护
GitHub Actions   -> SSH 部署或 Docker 部署
```

当前已确认的云服务器信息：

```text
ECS name: boundlesskore
Region: cn-hangzhou
OS: Ubuntu 22.04
Public IP: 47.96.7.204
Private IP: 172.19.125.149
Security Group: sg-bp1ebpwlet52s6xwk8ow
```

较稳的路线是：前端继续用 Cloudflare Pages；API 网关先用 Cloudflare Worker；RAG/OCR/长任务先放 `47.96.7.204`，通过 Cloudflare Tunnel、受保护 HTTPS 域名或 Nginx 同域反代让 Worker 调用。

建议先按以下代理路径占位：

```text
https://anzaidx.com/               -> Frontend
https://api.anzaidx.com/*          -> Worker API Gateway
https://anzaidx.com/rag/*          -> 47.96.7.204:/rag/*
https://anzaidx.com/agents/ocr/*   -> 47.96.7.204:/api/*
```

如果后续改成子域，也可切为：

```text
https://rag.anzaidx.com/*          -> 47.96.7.204
https://ocr.anzaidx.com/*          -> 47.96.7.204
```

## GitHub 仓库维护流程

1. 新建 GitHub 仓库，例如 `laikeyoufang-web`。
2. 把 `lumoffice/prototype` 和 `lumoffice/api-gateway` 放入仓库。
3. main 分支绑定 Cloudflare Pages。
4. Worker 使用 Wrangler 部署，后续可接 GitHub Actions。
5. 每次改模型配置或额度策略，先改 JSON 或 D1 seed，经页面验证后再发版。

## 前端优化下一步

当前是静态 HTML 原型，下一阶段建议迁移到 React/Vite：

- 把 00-11 页面拆成组件。
- 把 `config/*.json` 作为初始 seed，正式环境从 API 网关读取。
- 把 RAG 检索、内容生成、发布、复盘写回统一成 API client。
- 引入路由、状态管理、错误边界和 loading skeleton。
- 增加移动端真实交互验证和可访问性检查。

## 参考入口

- Cloudflare Pages Static HTML: https://developers.cloudflare.com/pages/framework-guides/deploy-anything/
- Cloudflare Wrangler configuration: https://developers.cloudflare.com/workers/wrangler/configuration/
- Cloudflare D1 getting started: https://developers.cloudflare.com/d1/get-started/
- OpenAI models: https://platform.openai.com/docs/models
- Claude models: https://docs.anthropic.com/en/docs/about-claude/models/overview
- Gemini models: https://ai.google.dev/gemini-api/docs/models

## 本地 API Gateway 联调台

本地开发时先启动两个服务：

```powershell
cd C:\Users\35160\Documents\Codex\lumoffice\prototype
python -m http.server 18765 --bind 127.0.0.1
```

```powershell
cd C:\Users\35160\Documents\Codex\lumoffice\api-gateway
npm install
npm run db:migrate:local
npm run dev -- --port 8787 --local
```

然后打开 `http://127.0.0.1:18765/index.html`，进入 `11 API 与模型调度`，在 `API Gateway 联调台` 中使用 `http://127.0.0.1:8787`。

联调按钮含义：

- `检测 Worker`：请求 `/api/health`，确认 Worker 与 CORS 可用。
- `解析路由`：请求 `/api/route/resolve`，确认 D1 路由表、额度策略、主模型和备用模型。
- `试调模块`：直接请求模块 endpoint，例如 `/api/content/public/generate` 或 `/api/knowledge/search`。

未配置模型密钥时，文本生成模块返回 `provider_not_configured` 是预期状态；未配置真实 RAG 地址时，知识库模块返回 `rag_not_configured` 是预期状态。它们说明调度、额度、审计和错误返回链路已经打通，只差生产密钥和服务地址。