llm-intelligence/DEPLOYMENT.md

LLM Intelligence Hub - 部署指南

版本: v1.1 日期: 2026-05-21 适用版本: Phase 1 / Phase 2 基础部署

---

环境要求

硬件

• CPU: 1 核+
• 内存: 512 MB+
• 磁盘: 5 GB+

软件

• Go 1.22+
• Node.js 20+
• PostgreSQL 16+
• Docker / Docker Compose

---

本地开发启动

1. 克隆仓库

git clone <repo-url> llm-intelligence
cd llm-intelligence

2. 初始化数据库

createdb llm_intelligence
psql llm_intelligence < db/migrations/001_phase1_core_tables.sql
psql llm_intelligence < db/migrations/002_sprint1_complete_schema.sql
psql llm_intelligence < db/migrations/003_phase2_region_pricing_metadata.sql
psql llm_intelligence < db/migrations/004_backfill_models_batch_id.sql
psql llm_intelligence < db/migrations/005_subscription_plan.sql

3. 配置环境变量

export DATABASE_URL="host=/var/run/postgresql dbname=llm_intelligence sslmode=disable"
export OPENROUTER_API_KEY="your-api-key"
export FEISHU_WEBHOOK="your-webhook-url"  # 可选

4. 启动后端

go run cmd/server/main.go

5. 启动前端开发服务

cd frontend
npm install
npm run dev

---

Docker 部署

当前容器镜像已经内置前端静态资源，app 服务会同时提供页面和 API。

使用 compose 启动完整环境

docker-compose up -d --build

启动后访问:

• Web UI: http://localhost:8080/
• Health: http://localhost:8080/health
• API: http://localhost:8080/api/v1/models

只构建镜像

docker build -t llm-hub .

运行示例:

docker run --rm -p 8080:8080 \
  -e DATABASE_URL="postgres://llm_hub:changeme@host.docker.internal:5432/llm_intelligence?sslmode=disable" \
  -e OPENROUTER_API_KEY="your-api-key" \
  llm-hub

---

配置说明

变量	必填	说明
DATABASE_URL	是	PostgreSQL 连接串
OPENROUTER_API_KEY	是	OpenRouter API Key
FEISHU_WEBHOOK	否	飞书告警 Webhook
PORT	否	服务端监听端口，默认 8080
FRONTEND_DIST_DIR	否	自定义静态资源目录，默认自动查找 frontend/dist

---

验证安装

curl http://localhost:8080/health
curl http://localhost:8080/api/v1/models

前端构建校验:

cd frontend
npm run build

Go 测试校验:

go test ./...

---

常见问题

Q: 前端构建失败?

确认:

• Node.js >= 20
• frontend/package-lock.json 与 npm ci 一致
• 本地没有依赖已删除的 frontend/src/data/latest_models.json

Q: docker-compose up -d 后页面空白?

先执行:

docker-compose up -d --build

然后检查:

docker-compose logs -f app
curl http://localhost:8080/

Q: API 返回 database not configured?

说明 DATABASE_URL 未注入或格式不正确，先执行:

echo "$DATABASE_URL"

---

升级路径

• Phase 2: 告警订阅 / 用户系统 / 付费分析
• Phase 3: 多数据源 / 自动发现 / ELO 评分