YoVinchen
c3bad0f186
Some checks failed
verify / verify (push) Has been cancelled
Expose the verified synthetic retrieval path through a typed React client and a non-root Nginx edge while keeping database credentials and data-network reachability out of the browser tier. A fixed-origin gateway preserves request boundaries and now closes upstream streams even when downstream disconnects before body iteration. The deployment ADR and runbooks record the four-network topology and its accepted Web edge-egress risk. Constraint: The previously exposed Bailian key must be revoked and no live provider credential may enter Git, images, logs, or the browser. Rejected: Connect Web directly to the data network | expands lateral reach to PostgreSQL. Rejected: Publish the database-aware API on the edge network | gives a credential-bearing process a public default route. Rejected: Buffer streaming responses in either proxy | prevents incremental chat delivery in the future. Confidence: high Scope-risk: moderate Reversibility: clean Directive: Do not mark Stage 1 or Stage 2 complete until the rotated-key live smoke and remaining stage gates pass. Tested: make verify; 65 backend tests; 14 frontend tests; Docker image build; container health and isolation probes; real HTTP demo/status/search/docs/OpenAPI checks. Not-tested: Live Bailian models, real document ingestion, business chat SSE generation, and final browser screenshot automation because the browser skill runtime was unavailable.
92 lines
3.3 KiB
Markdown
92 lines
3.3 KiB
Markdown
# React 离线检索演示运行手册
|
||
|
||
本手册用于启动 React + Nginx + gateway + FastAPI + PostgreSQL/pgvector 的同源离线演示。当前页面只展示合成数据的检索和重排结果，不调用百炼，不生成大模型答案，也不构成地质勘查结论。
|
||
|
||
## 1. 一键启动
|
||
|
||
首次运行先创建本地数据库 Secret：
|
||
|
||
```bash
|
||
make setup-hooks
|
||
bash scripts/init-local-secrets.sh
|
||
docker compose up -d --build web
|
||
docker compose --profile tools run --rm seed-demo-offline
|
||
```
|
||
|
||
`web` 的依赖链会依次等待 `db -> migrate -> api -> gateway`。离线 seed 完成后刷新页面，即可看到 20/20/20 的演示数据状态。
|
||
|
||
访问入口：
|
||
|
||
- React 演示：<http://127.0.0.1:8000/>
|
||
- FastAPI Swagger：<http://127.0.0.1:8000/docs>
|
||
- 数据库 readiness：<http://127.0.0.1:8000/health/ready>
|
||
- synthetic 状态：<http://127.0.0.1:8000/api/v1/demo/status>
|
||
|
||
## 2. 推荐演示流程
|
||
|
||
1. 确认页面顶部持续显示“合成数据、离线模式、不调用云端模型”。
|
||
2. 确认切片、向量和可检索计数均为 20。
|
||
3. 选择示例问题或输入“花岗斑岩 铜矿化”，设置返回 3 条。
|
||
4. 提交检索，查看合成标题、证据摘录、页码、演示排序分和不透明 citation ID。
|
||
5. 说明 citation ID 尚不能打开真实报告页，当前没有 LLM 生成答案。
|
||
6. 缩窄浏览器到移动宽度，验证表单和来源卡片仍可完整阅读。
|
||
|
||
## 3. 本地前端开发
|
||
|
||
先让 Docker Web/API 链保持运行，再启动 Vite：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm ci
|
||
npm run dev
|
||
```
|
||
|
||
Vite 只监听 `127.0.0.1`，并把 `/api`、`/health` 和 `/openapi.json` 代理到本机 Docker Web 入口。前端 API 基址保持同源，构建产物中不存在数据库地址或百炼凭证。
|
||
|
||
后端 OpenAPI 改变后重新生成类型：
|
||
|
||
```bash
|
||
cd frontend
|
||
npm run generate:api
|
||
npm run typecheck
|
||
```
|
||
|
||
生成脚本会检查 demo status/search 路径是否存在，然后覆盖 `src/api/schema.generated.ts`；生成结果必须随 API 契约变更一起提交。
|
||
|
||
## 4. 质量门禁
|
||
|
||
```bash
|
||
make verify
|
||
docker compose --env-file .env.example ps -a
|
||
```
|
||
|
||
统一门禁包括：
|
||
|
||
- Secret、Markdown 链接和 Git diff 检查；
|
||
- Ruff、严格 mypy 和 pytest；
|
||
- Prettier、ESLint、严格 TypeScript、Vitest 和 Vite production build；
|
||
- Compose 配置与网络/Secret 合同测试。
|
||
|
||
容器级验收还应确认：
|
||
|
||
- 只有 `web` 发布 `127.0.0.1:8000`；
|
||
- `web` 和 `gateway` 没有 Secret；
|
||
- `api` 只连接 internal data 网络，公网 socket 探测失败；
|
||
- `gateway` 公网 socket 探测失败；Web 因普通 edge 网络可技术性出网，但无 Secret、无数据网络和挂载，此残余风险记录于 ADR-0004；
|
||
- `/api`、健康检查和 Swagger 经 Web 同源代理可用；
|
||
- SSE 响应在 gateway 与 Nginx 均不被整体缓冲。
|
||
|
||
## 5. 停止与清理
|
||
|
||
停止容器但保留 PostgreSQL 数据：
|
||
|
||
```bash
|
||
docker compose down
|
||
```
|
||
|
||
不要在需要保留验收数据时使用 `docker compose down -v`。该命令会删除 PostgreSQL volume。
|
||
|
||
## 6. 当前边界
|
||
|
||
已实现的是可运行的离线检索演示；尚未实现登录、真实知识库、文件上传、OCR、生成答案、可点击原文页、会话、反馈、正式评测面板和真实百炼模型探测。只有轮换后的新 Key 完成三模型 smoke 后，Stage 1 才能标记为完成，Stage 2 也不能因页面可见而提前标记为完成。
|