dd58c18fe3
Add a top-level README plus production configuration, API, and rollout documentation. Also align deployment and runbook docs with the current runtime semantics, ports, and daily pipeline entrypoints.
161 lines
4.1 KiB
Markdown
161 lines
4.1 KiB
Markdown
# LLM Intelligence Hub
|
||
|
||
面向 LLM 模型、定价与日报产出的情报采集项目，当前仓库提供：
|
||
|
||
- Go 采集脚本：采集 OpenRouter、多源补充数据与官方补录数据
|
||
- PostgreSQL 数据层：保存模型、区域定价、订阅套餐、日报与运行审计
|
||
- Go HTTP API：提供模型列表、套餐列表、最新正式日报入口
|
||
- Vite + React 前端：提供 Dashboard / Explorer 两个只读页面
|
||
- Shell 运维脚本：迁移、调度、备份、恢复、验收与性能门禁
|
||
|
||
## 当前能力边界
|
||
|
||
- 真实生产主链路是“采集/导入脚本 + PostgreSQL + 日报生成器 + API Server + Nginx”
|
||
- 最新正式日报由 `scripts/run_daily.sh` 生成，并写入 `daily_report` / `report_runs`
|
||
- 手工复跑使用 `scripts/run_real_pipeline.sh`，不会把产物标记成正式日报
|
||
- 历史补跑使用 `scripts/rebuild_historical_report.sh YYYY-MM-DD`
|
||
- HTTP API 当前未内建认证、授权和限流；公网暴露前必须在网关层补齐
|
||
|
||
## 目录概览
|
||
|
||
```text
|
||
cmd/server/ Go API Server
|
||
internal/ 通用内部库（collector、retry）
|
||
scripts/ 采集、导入、日报、验收、运维脚本
|
||
db/migrations/ PostgreSQL 迁移
|
||
frontend/ Vite + React 前端
|
||
reports/daily/ 日报产物与归档
|
||
ops/ 运维配置（如 logrotate）
|
||
docs/ 补充说明与上线文档
|
||
```
|
||
|
||
## 本地启动
|
||
|
||
### 1. 准备环境
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
至少需要配置：
|
||
|
||
- `DATABASE_URL`
|
||
- `OPENROUTER_API_KEY`（仅真实采集需要）
|
||
|
||
详细变量说明见 [docs/CONFIGURATION.md](docs/CONFIGURATION.md)。
|
||
|
||
### 2. 应用数据库迁移
|
||
|
||
```bash
|
||
bash scripts/apply_migration.sh
|
||
```
|
||
|
||
### 3. 启动 API Server
|
||
|
||
```bash
|
||
go run ./cmd/server
|
||
```
|
||
|
||
默认端口为 `8080`，可通过 `PORT` 覆盖。
|
||
|
||
### 4. 启动前端开发环境
|
||
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
## 生产运行主链路
|
||
|
||
### 正式日报调度
|
||
|
||
```bash
|
||
bash scripts/run_daily.sh
|
||
```
|
||
|
||
该脚本负责：
|
||
|
||
1. OpenRouter 真实采集
|
||
2. 多源补充同步
|
||
3. 官方导入脚本执行
|
||
4. 数据质量检查
|
||
5. Markdown / HTML 日报生成
|
||
6. 日报归档
|
||
7. `daily_report` / `report_runs` 审计写入
|
||
8. 失败时降级复制昨日报告并可选飞书告警
|
||
|
||
### 手工真实复跑
|
||
|
||
```bash
|
||
bash scripts/run_real_pipeline.sh
|
||
```
|
||
|
||
适用于联调、排障、上线后人工验证。该入口写入：
|
||
|
||
- `run_kind=manual`
|
||
- `trigger_source=pipeline`
|
||
- `is_official_daily=false`
|
||
|
||
### 历史补跑
|
||
|
||
```bash
|
||
bash scripts/rebuild_historical_report.sh 2026-05-13
|
||
```
|
||
|
||
该入口写入：
|
||
|
||
- `run_kind=historical_rebuild`
|
||
- `trigger_source=rebuild_script`
|
||
- `is_official_daily=false`
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
go test ./...
|
||
bash scripts/test.sh
|
||
bash scripts/verify_pre_phase6.sh
|
||
bash scripts/verify_phase6.sh
|
||
bash healthcheck.sh
|
||
cd frontend && npm run test -- --run
|
||
cd frontend && npm run build
|
||
```
|
||
|
||
## API 概览
|
||
|
||
- `GET /health`
|
||
- `GET /api/v1/models`
|
||
- `GET /api/v1/subscription-plans`
|
||
- `GET /api/v1/reports/latest`
|
||
- `GET /api/v1/reports/latest/markdown`
|
||
- `GET /api/v1/reports/latest/html`
|
||
|
||
完整字段与示例见 [docs/API_REFERENCE.md](docs/API_REFERENCE.md)。
|
||
|
||
## 文档索引
|
||
|
||
- [docs/CONFIGURATION.md](docs/CONFIGURATION.md)：环境变量、运行语义、配置约束
|
||
- [docs/API_REFERENCE.md](docs/API_REFERENCE.md)：API 入口、返回体与排障说明
|
||
- [docs/PRODUCTION_CHECKLIST.md](docs/PRODUCTION_CHECKLIST.md)：生产上线前检查、发布与回滚流程
|
||
- [DEPLOYMENT.md](DEPLOYMENT.md)：部署步骤与快速启动
|
||
- [RUNBOOK.md](RUNBOOK.md)：运维巡检、故障排查、备份恢复
|
||
- [TECHNICAL_DESIGN.md](TECHNICAL_DESIGN.md)：详细技术设计与数据模型演进背景
|
||
- [docs/PERFORMANCE_TEST.md](docs/PERFORMANCE_TEST.md)：性能基线
|
||
|
||
## 生产上线最低门禁
|
||
|
||
建议把以下检查作为发布前硬门禁：
|
||
|
||
```bash
|
||
bash scripts/verify_pre_phase6.sh
|
||
bash scripts/verify_phase6.sh
|
||
```
|
||
|
||
上线后首轮冒烟建议至少覆盖：
|
||
|
||
```bash
|
||
curl -fsS http://127.0.0.1:8080/health
|
||
curl -fsS http://127.0.0.1:8080/api/v1/models
|
||
curl -fsS http://127.0.0.1:8080/api/v1/reports/latest
|
||
```
|