xuelong/Cloud-Tour-to-Libo
0
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: streamline platform and secure data access

Browse Source 
- move the relational data center to MySQL and a standalone workbench\n- add Interface Center API credentials, policies, logs, and DBeaver SSH guidance\n- harden authentication and deployment while retiring unused management surfaces
This commit is contained in:
xuelong committed 2026-08-25 02:06:28 -07:00
1 parent 15368f2779
commit 3dd5731751
137 files changed
+8571 -14151
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/API_REFERENCE.md
+2 -9
View File
@@ -26,24 +26,17 @@ http://localhost:8102/docs
| `/v1/admin/auth/login` | `POST` | 管理员登录 |
| `/v1/admin/auth/me` | `GET` | 当前登录用户 |
| `/v1/admin/projects` | `GET/POST` | 项目管理 |
| `/v1/admin/ontology-schemas` | `GET` | 当前项目创建的 Schema 列表 |
| `/v1/admin/ontology-schemas/current` | `GET` | 当前 schema |
| `/v1/admin/source-profiles` | `GET/POST/PATCH` | 数据源管理 |
| `/v1/admin/batches` | `GET` | 批次管理 |
| `/v1/admin/entities` | `GET` | 候选实体列表 |
| `/v1/admin/conflicts` | `GET` | 冲突列表 |
| `/v1/admin/publish-jobs` | `GET/POST` | 发布任务 |
| `/v1/admin/graph/overview` | `GET` | 图谱概览 |
| `/v1/admin/graph/query` | `POST` | 图谱查询 |
| `/v1/admin/plaza/overview` | `GET` | 图谱广场概览 |
| `/v1/admin/manual-ingest/extract` | `POST` | 手动抽取 |
| `/v1/admin/travel/assistant-query` | `POST` | 旅行客服问答 |
| `/v1/openapi/knowledge-qa/query` | `POST` | 百姓惠智能客服第三方问答接口 |
| `/v1/admin/travel/customer-service-query` | `POST` | 兼容旧版外部问答接口 |
| `/v1/admin/super-agent/run` | `POST` | Super Agent 任务 |
| `/v1/admin/roles` | `GET/POST` | 角色管理 |
| `/v1/admin/users` | `GET/POST` | 用户管理 |
| `/v1/admin/areas/tree` | `GET` | 区域树 |
| `/v1/admin/notifications` | `GET` | 通知列表 |
## 登录示例
@@ -85,7 +78,7 @@ curl http://localhost:8102/v1/admin/travel/assistant-query \
该接口用于对接外部客服系统。调用方传入用户自然语言问题，服务端默认选择百姓惠旅行社知识图谱，按“LLM 生成只读 Cypher -> FalkorDB 图查询 -> LLM 基于证据组织答案”的链路返回客服话术和图谱证据。生产环境需要配置问答环节 LLM。
认证方式使用接口 Key。Key 可以在后台 `系统 -> Agent 设置 -> 外部图谱问答 API` 维护；同时兼容 `.env` / `docker-compose.yml` 的 `INGEST_API_KEYS`。同一模块底部可以配置“问答环节 LLM 模型”，外部客服话术融合会优先使用该模型，未填写时继承全局 LLM：
认证方式使用接口 Key，通过 `.env` 或 `docker-compose.yml` 的 `INGEST_API_KEYS` 配置。问答环节使用 `LLM_API_BASE`、`LLM_API_KEY` 和 `LLM_MODEL` 指定的模型：
```bash
curl http://localhost:8102/v1/openapi/knowledge-qa/query \
docs/ARCHITECTURE.md
+7 -9
View File
@@ -23,7 +23,7 @@ flowchart TB
| 服务 | 职责 |
| --- | --- |
| `api` | 提供 `/v1/admin/*` API，挂载 `/admin` 前端页面，连接 PostgreSQL 与 FalkorDB |
| `postgres` | 保存后台业务数据、用户权限、项目、候选实体、审核记录和任务 |
| `postgres` | 保存项目、Schema、结构化业务数据、用户权限和后台流程支撑数据 |
| `falkordb-seed` | 首次启动时把仓库内的 `snapshots/falkordb/dump.rdb` 写入数据卷 |
| `falkordb` | 保存图数据库，支持 Cypher/Redis 协议访问和 FalkorDB Browser |
@@ -35,7 +35,7 @@ flowchart TB
| `app/config.py` | 环境变量配置 |
| `app/db.py` | PostgreSQL 连接池 |
| `app/api/` | 管理后台 API 路由 |
| `app/agents/` | 采集、抽取、对齐、审计和外部站点 Agent |
| `app/agents/` | 采集、抽取、对齐和外部站点 Agent |
| `app/kg_core/` | 空间图谱与核心图谱辅助逻辑 |
| `app/schemas/` | 抽取 schema |
| `app/security.py`、`app/auth.py` | 登录、令牌和权限相关逻辑 |
@@ -46,18 +46,16 @@ flowchart TB
| --- | --- |
| `admin-web/src/App.tsx` | 管理后台主应用与路由 |
| `admin-web/src/api.ts` | API 客户端 |
| `admin-web/src/panels/plaza/` | 图谱广场、用户查询、手动抽取和 Super Agent |
| `admin-web/src/panels/acquisition/` | 数据源、批次和冲突工作台 |
| `admin-web/src/panels/review/` | 证据质量、字段审核、专家签核和资产库 |
| `admin-web/src/panels/modeling/` | Schema、词表和健康检查 |
| `admin-web/src/panels/publish/` | 发布与回滚 |
| `admin-web/src/panels/system/` | 用户、权限、区域、通知、Agent 设置和日志 |
| `admin-web/src/panels/plaza/` | 数据大屏、业务问答、图谱浏览和 Super Agent |
| `admin-web/src/panels/data-platform/` | 项目数据库、表、记录、CSV 与 SQL 工作区 |
| `admin-web/src/panels/modeling/` | 当前项目 Schema 的只读展示 |
| `admin-web/src/panels/system/` | 用户、权限、Agent 任务和调用日志 |
## 数据层
PostgreSQL 和 FalkorDB 承担不同职责：
- PostgreSQL：结构化管理数据、审核过程数据、用户权限、任务、来源、候选实体和证据。
- PostgreSQL：项目、Schema、结构化业务数据、用户权限，以及 Agent 所需的内部流程数据。
- FalkorDB：图谱实体、关系、路线、资源、POI、空间索引和面向查询的图结构。
默认配置：
docs/DEPLOYMENT.md
+73 -25
View File
@@ -7,9 +7,9 @@
- Docker Desktop 或 Docker Engine
- Docker Compose v2
- 至少 4 GB 可用内存
- 至少 3 GB 可用磁盘空间
- 开发环境至少 10 GB、生产环境至少 50 GB 可用磁盘空间，并单独规划异地备份容量
## 一键启动
## 本地开发启动
```bash
docker compose up -d --build
@@ -21,20 +21,18 @@ docker compose up -d --build
http://localhost:8102/admin
```
服务器部署后把 `localhost` 换成服务器 IP 或域名。例如本项目迁移到 `8.163.40.99` 后：
```text
http://8.163.40.99:8102/admin
http://8.163.40.99:8102/docs
http://8.163.40.99:8102/openapi.json
```
默认账号：
以下默认账号只允许本地开发使用：
```text
admin@example.com / change-me
```
生产环境必须先完成后文中的密钥、域名、HTTPS 和防火墙配置，再使用服务器覆盖文件启动：
```bash
docker compose -f docker-compose.yml -f docker-compose.server.yml up -d --build
```
## 首次启动会发生什么
1. 构建 API 镜像，并打包 React 管理后台。
@@ -103,6 +101,20 @@ sudo loginctl enable-linger dockerop
这样 rootless Docker 可以由 systemd 用户服务长期托管。
## 生产安全入口
服务器覆盖配置默认令 API 只监听 `127.0.0.1:8102`。公网只能通过 Nginx 的
HTTPS 443 端口访问，不再直接开放 8102。可复制
`deploy/nginx/travel-kg.conf.example`，替换域名和证书路径后启用。
安全组入站规则建议仅保留：
- `443/tcp`：所有合法业务来源；
- `22/tcp`：仅运维固定 IP 或 VPN 网段；
- `80/tcp`：仅用于跳转 HTTPS 或证书签发。
严禁向公网开放 `8102`、`3307`、`5433`、`6380` 和 `3002`。
## 端口配置
可以在启动时覆盖端口：
@@ -119,10 +131,13 @@ docker compose up -d --build
| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `API_HOST_BIND` | `0.0.0.0` | API/后台监听地址 |
| `API_HOST_BIND` | `0.0.0.0` | 本地 Compose 的 API/后台监听地址 |
| `API_BIND_HOST` | 服务器覆盖默认 `127.0.0.1` | 生产 Uvicorn 监听地址，只允许 Nginx 转发 |
| `API_PORT` | `8102` | FastAPI 与管理后台 |
| `POSTGRES_HOST_BIND` | `127.0.0.1` | PostgreSQL 只绑定服务器本机 |
| `POSTGRES_PORT` | `5433` | PostgreSQL 映射端口 |
| `MYSQL_HOST_BIND` | `127.0.0.1` | MySQL 只绑定服务器本机，DBeaver 经 SSH 隧道接入 |
| `MYSQL_PORT` | `3307` | MySQL 服务器本机映射端口，不向公网开放 |
| `FALKORDB_HOST_BIND` | `127.0.0.1` | FalkorDB Redis 协议只绑定服务器本机 |
| `FALKORDB_PORT` | `6380` | FalkorDB Redis 协议端口 |
| `FALKORDB_BROWSER_HOST_BIND` | `127.0.0.1` | FalkorDB Browser 只绑定服务器本机 |
@@ -130,7 +145,9 @@ docker compose up -d --build
## 环境变量
Docker Compose 已提供可运行默认值。生产部署时建议改成 `.env` 文件或部署平台的环境变量。
基础 Docker Compose 提供开发默认值；服务器覆盖配置会对关键变量使用必填校验，
任何占位密码、弱签名密钥、公开 MySQL 绑定、通配 CORS 或不可信 Host 都会令
应用拒绝启动。
服务器首次部署建议复制模板后修改：
@@ -142,16 +159,16 @@ cp .env.example .env
```env
AUTH_SECRET=换成32位以上随机字符串
AUTH_DEFAULT_PASSWORD=换成后台管理员密码
INGEST_API_KEYS=换成给外部系统的接口Key
AUTH_DEFAULT_PASSWORD=换成12位以上后台管理员密码
INTERFACE_API_SECRET=与AUTH_SECRET不同的32位以上随机字符串
INGEST_API_KEYS=至少24位的外部系统接口Key
CORS_ALLOWED_ORIGINS=https://你的后台域名
TRUSTED_HOSTS=你的后台域名
LLM_API_BASE=你的OpenAI兼容模型地址
LLM_API_KEY=你的模型Key
```
部署后也可以在后台 `系统 -> Agent 设置` 中配置：
- `全局 LLM 配置`：填写 OpenAI 兼容模型地址、模型 ID、LLM API Key。
- `外部图谱问答 API`：位于页面底部，维护给其他系统调用的 `X-KG-API-Key`，设置默认图谱、默认 LLM 策略和“问答环节 LLM 模型”。该模型优先用于外部客服问答，留空则继承全局 LLM。
新系统不再提供后台 Agent 设置页面。LLM 与外部接口 Key 统一通过 `.env`、Compose 环境变量或部署平台的密钥配置维护。
| 变量 | 说明 |
| --- | --- |
@@ -159,9 +176,16 @@ LLM_API_KEY=你的模型Key
| `DATABASE_URL` | 后端连接 PostgreSQL 的 URL |
| `DB_SCHEMA` | 默认 `kg_admin_new2` |
| `DB_MIGRATIONS_ENABLED` | 快照部署默认 `false` |
| `DATA_MYSQL_SSH_HOST`、`DATA_MYSQL_SSH_PORT` | DBeaver SSH 标签页使用的服务器地址和 SSH 端口 |
| `DATA_MYSQL_ADMIN_HOST`、`DATA_MYSQL_ADMIN_PORT` | DBeaver Main 标签页使用的隧道远端 MySQL 地址，默认 `127.0.0.1:3307` |
| `DATA_MYSQL_AUDIT_ENABLED` | 只有数据库审计真实启用后才设置为 `true` |
| `DATA_SQL_CONSOLE_WRITE_ENABLED` | 默认 `false`，生产 SQL 控制台保持只读 |
| `DATA_BACKUP_ENABLED` | 自动备份任务真实部署后才设置为 `true` |
| `DATA_BACKUP_PASSPHRASE_FILE` | 仓库外的备份加密口令文件，权限必须为 600 |
| `FALKORDB_HOST` | Docker 内默认 `falkordb` |
| `FALKORDB_GRAPH` | 默认业务图 `guiyang_new2` |
| `AUTH_SECRET` | JWT 签名密钥，生产必须替换 |
| `INTERFACE_API_SECRET` | 接口密钥散列专用密钥，不得与 JWT 密钥复用 |
| `AUTH_DEFAULT_USERNAME` | 默认管理员用户名 |
| `AUTH_DEFAULT_PASSWORD` | 默认管理员密码 |
| `LLM_API_BASE` | OpenAI 兼容模型服务地址，可选 |
@@ -178,20 +202,21 @@ LLM_API_KEY=你的模型Key
给外部系统对接时，只开放这个接口即可：
```text
POST http://8.163.40.99:8102/v1/openapi/knowledge-qa/query
POST https://你的域名/v1/openapi/knowledge-qa/query
```
`/v1/admin/travel/customer-service-query` 会继续保留为兼容旧调用，新接入的第三方系统建议统一使用 `/v1/openapi/knowledge-qa/query`。
服务器安全组需要放行 TCP `8102`。如果服务器本机 `curl http://127.0.0.1:8102/v1/admin/health` 正常，但外部访问 `http://8.163.40.99:8102` 超时，优先检查云控制台安全组/防火墙入方向规则。
不要把 `5433`、`6380`、`3002` 暴露到公网；默认 Compose 已把这些数据端口绑定到 `127.0.0.1`。
生产环境必须在后台 `外部图谱问答 API` 或环境变量 `INGEST_API_KEYS` 中配置至少一个接口 Key；未配置时，对外问答接口会返回 `503`，避免无鉴权开放。
生产服务器不应放行 TCP `8102`。服务器本机可用
`curl http://127.0.0.1:8102/v1/admin/health` 检查应用，外部统一访问
`https://你的域名/`。不要把 `3307`、`5433`、`6380`、`3002` 暴露到公网。
生产环境必须通过环境变量 `INGEST_API_KEYS` 配置至少一个接口 Key；未配置时，对外问答接口会返回 `503`，避免无鉴权开放。
接口 Key 是给第三方系统调用本接口用的访问凭证；问答环节 LLM 的 API Key 是本系统调用大模型用的凭证，两者不要混用。
请求示例：
```bash
curl http://8.163.40.99:8102/v1/openapi/knowledge-qa/query \
curl https://你的域名/v1/openapi/knowledge-qa/query \
-H 'Content-Type: application/json' \
-H 'X-KG-API-Key: 你的INGEST_API_KEYS之一' \
-d '{
@@ -205,6 +230,29 @@ curl http://8.163.40.99:8102/v1/openapi/knowledge-qa/query \
}'
```
## MySQL 加密备份
先在代码仓库之外创建口令文件：
```bash
sudo install -d -m 700 /etc/travel-kg/secrets
openssl rand -base64 48 | sudo tee /etc/travel-kg/secrets/mysql-backup-passphrase >/dev/null
sudo chmod 600 /etc/travel-kg/secrets/mysql-backup-passphrase
```
执行备份和校验：
```bash
export DATA_BACKUP_PASSPHRASE_FILE=/etc/travel-kg/secrets/mysql-backup-passphrase
./scripts/backup_mysql_encrypted.sh
./scripts/verify_mysql_backup.sh ./backups/mysql/mysql-all-时间.sql.gz.enc
```
备份采用 `mysqldump --single-transaction`、gzip 和 AES-256/PBKDF2，并生成
SHA-256 校验文件。`.enc`、`.sha256`、`.json` 三个文件必须同步到独立账号的
异地对象存储。校验脚本不等于恢复演练；至少每月在隔离 MySQL 实例执行一次
完整恢复，确认账号、表结构和业务数据均可恢复。
默认问答链路需要配置问答环节 LLM；可在后台 `外部图谱问答 API -> 问答环节 LLM 模型` 单独配置，也可以继承全局 LLM。
主要返回字段：
@@ -279,5 +327,5 @@ API_PORT=18102 docker compose up -d
- 不要把真实 `.env`、LLM key、高德 key 提交到仓库。
- 用反向代理提供 HTTPS。
- 给 PostgreSQL 和 FalkorDB 配置持久化备份。
- 如果面向公网，限制数据库端口暴露，只暴露 API/前端。
- MySQL、PostgreSQL 和 FalkorDB 全部只绑定服务器本机；DBeaver 经 SSH 私钥隧道接入，公网只暴露 HTTPS 和受控 SSH。
- 开启日志采集和容器监控。
docs/PROJECT_OVERVIEW.md
+10 -15
View File
@@ -1,11 +1,10 @@
# 系统介绍
旅行知识图谱管理系统是 `new2` 版本的城市与旅行领域知识图谱平台，面向景区、旅行社、文旅运营和智能客服场景。系统把采集资料、百科文本、POI 空间数据、线路产品、酒店/餐饮/车辆等资源沉淀为可审核、可发布、可查询的图谱资产。
旅行知识图谱管理系统是 `new2` 版本的城市与旅行领域知识图谱平台，面向景区、旅行社、文旅运营和智能客服场景。系统把项目 Schema、结构化业务数据、POI 空间数据、线路产品、酒店/餐饮/车辆等资源统一组织为可管理、可查询的业务数据与图谱资产。
## 目标用户
- 文旅运营人员：查看图谱覆盖、数据质量、缺口和发布状态。
- 数据标注与审核人员：处理实体字段、证据来源、冲突合并和专家签核。
- 文旅运营人员：查看数据大屏、图谱覆盖和业务数据。
- 产品和线路人员：维护固定线路、景点组合、报价说明和资源约束。
- 智能客服研发人员：基于图谱接口构建线路问答、周边资源推荐和报价查询。
- 工程维护人员：通过 Docker、快照和脚本复现系统与数据。
@@ -14,25 +13,21 @@
| 能力 | 说明 |
| --- | --- |
| 数据源与批次管理 | 管理来源、采集批次、原始记录和质量摘要 |
| 实体审核 | 查看候选实体、字段决策、证据链、审查历史和合并 |
| 图谱广场 | 汇总图谱规模、使用情况、健康告警和用户查询 |
| Schema 管理 | 管理 ontology schema、DSL、版本和发布记录 |
| 证据质量 | 聚合 POI 证据、资源质量和字段可信度 |
| 发布与回滚 | 创建发布任务、查看 diff、回滚图谱版本 |
| 图谱中心 | 创建和管理图谱项目及项目 Schema |
| 数据中心 | 管理项目数据库、数据表、记录、CSV 和 SQL 工作区 |
| 知识广场 | 提供数据大屏、业务问答和图谱浏览 |
| 本体 Schema | 只读展示图谱中心当前项目创建的 Schema 与版本 |
| 城市空间图谱 | 使用高德 POI 与空间网格支持周边检索 |
| 旅行客服 Agent | 支持线路清单、线路匹配、线路报价、酒店资源、车辆和附近资源查询 |
| 权限与组织 | 内置角色、能力矩阵、用户和区域责任管理 |
| 权限与组织 | 内置角色、能力矩阵和用户管理 |
## 典型业务流程
```mermaid
flowchart LR
A["采集/导入资料"] --> B["抽取候选实体"]
B --> C["字段证据与质量检查"]
C --> D["人工审核/冲突合并"]
D --> E["发布到 FalkorDB 图谱"]
E --> F["图谱查询/客服问答/运营分析"]
A["图谱中心创建项目与 Schema"] --> B["数据中心管理业务数据"]
B --> C["数据大屏与图谱浏览"]
C --> D["业务问答与运营分析"]
```
## 随仓库发布的内容
docs/data-center-mysql-interface-center.md
+128
View File
@@ -0,0 +1,128 @@
# 数据中心 MySQL 与接口中心部署说明
## 已确定的系统边界
- PostgreSQL：继续保存账号、权限、图谱项目与 Schema 等系统元数据。
- FalkorDB：继续保存已发布知识图谱节点和关系。
- MySQL：只负责“数据中心”的关系型业务数据。
- 接口中心：只通过受控 HTTPS API 访问 MySQL 数据中心，不允许外部用户执行任意 SQL。
- DBeaver：仅供受信任的数据管理员通过 SSH 隧道管理 MySQL，使用独立 MySQL 用户和 `GRANT` 权限；不复用接口密钥，也不公开 MySQL 端口。
- SQL 控制台：生产默认只读；写入通过数据表页面执行，以保留记录级变更历史，物理删除始终禁止。
每个数据中心数据库都是真实 MySQL Database：中文名称只用于页面显示，英文数据库编码直接作为物理 MySQL 数据库名。前端数据中心的现有 URL、布局和 `/v1/admin/data-platform/*` 契约保持不变。
## 配置
关键环境变量：
```dotenv
DATA_MYSQL_URL=mysql://data_center:strong-password@mysql:3306/platform_control
DATA_MYSQL_REQUIRED=true
DATA_MYSQL_POOL_MIN_SIZE=2
DATA_MYSQL_POOL_MAX_SIZE=20
INTERFACE_API_SECRET=another-long-random-secret
DATA_MYSQL_DIRECT_ACCESS_ENABLED=false
MYSQL_HOST_BIND=127.0.0.1
MYSQL_PORT=3307
DATA_MYSQL_DIRECT_TRANSPORT=SSH 隧道（强制）
DATA_MYSQL_SSH_TUNNEL_REQUIRED=true
DATA_MYSQL_SSH_HOST=server.example.com
DATA_MYSQL_SSH_PORT=22
DATA_MYSQL_SSH_AUTH_METHOD=SSH 私钥 / SSH Agent
DATA_MYSQL_ADMIN_HOST=127.0.0.1
DATA_MYSQL_ADMIN_PORT=3307
DATA_MYSQL_ADMIN_ACCOUNT_POLICY=一人一号 · 单库授权 · 禁止 root
DATA_MYSQL_AUDIT_ENABLED=false
DATA_SQL_CONSOLE_WRITE_ENABLED=false
DATA_BACKUP_ENABLED=false
```
`MYSQL_HOST_BIND` 在生产环境必须保持 `127.0.0.1`。`DATA_MYSQL_DIRECT_ACCESS_ENABLED` 只表示管理员接入是否完成运维配置，不会开放端口；本项目不提供公开 MySQL 直连模式。只有数据库审计真实启用后，才把 `DATA_MYSQL_AUDIT_ENABLED` 改成 `true`。
应用会记录 API 调用、记录新增/修改/软删除以及 SQL 控制台的成功、失败和拒绝
事件；SQL 审计只保存语句 SHA-256，不保存可能包含敏感值的原文。DBeaver 绕过
应用，因此仍必须由数据库审计能力单独留痕，未完成前不得开放长期写权限。
生产 MySQL 开启 ROW Binlog、`sync_binlog=1` 与
`innodb_flush_log_at_trx_commit=1`，用于时间点恢复与事务落盘；加密备份脚本和
恢复要求见 `docs/DEPLOYMENT.md`。
`platform_control` 保存数据库目录、表定义、数据审计、接口客户端、密钥哈希、权限策略与接口调用日志。完整接口密钥不会保存，只保存带服务端 pepper 的 HMAC-SHA256 哈希。
## 首次部署
```bash
docker compose up -d mysql
docker compose up -d --build api
```
接口中心页面：`/admin/system/interfaces`。
页面以“服务器被访问”为方向：`DBeaver 管理接入`只给受信任的数据管理员展示 SSH 隧道参数，`HTTPS API`负责电脑、设备和业务系统的身份、密钥、最小权限与调用日志。接口中心不会主动连接外部数据库。
## DBeaver 安全连接
DBeaver 不使用 URL 模式直接填写服务器公网地址。按两组参数配置：
1. `SSH` 标签页：`Host/IP=服务器域名`、`Port=22`、认证方式使用私钥或 SSH Agent；
2. `Main` 标签页：`Server Host=127.0.0.1`、`Port=3307`、`Database=获授权数据库编码`；
3. 关闭 `Show all databases`；
4. 使用运维为当前人员签发的独立 MySQL 账号，禁止使用 `root` 和后端服务账号 `data_center`；
5. 默认只授予 `SELECT`，写入和结构修改权限按需临时授予。
运维人员可在服务器上创建或撤销独立账号：
```bash
./scripts/mysql_admin_account.sh create zhangsan tourism_data read
./scripts/mysql_admin_account.sh create lisi tourism_data write
./scripts/mysql_admin_account.sh revoke zhangsan
```
脚本只授予指定数据库权限：`read` 为 `SELECT/SHOW VIEW`，`write` 额外包含
`INSERT/UPDATE/DELETE`，不授予建库、删库、授权、文件或系统库权限；账号连续
失败 5 次锁定一天，密码 90 天过期。MySQL 端口仍必须绑定回环地址，账号的
`'%'` 主机范围不能替代网络隔离。
接口中心不会显示或复制 MySQL 密码。服务器安全组只允许受控来源访问 SSH 与 HTTPS，不开放 `3307`。
外部数据接口前缀：`/v1/openapi/data`。调用时使用：
```http
Authorization: Bearer YOUR_API_KEY
```
## 迁移旧数据中心
先预览，不写入：
```bash
python3 scripts/migrate_data_center_postgres_to_mysql.py
```
确认计划后执行：
```bash
python3 scripts/migrate_data_center_postgres_to_mysql.py --execute
```
如果目标 MySQL 中已存在同编码数据库，脚本默认拒绝覆盖。只有确认目标可以重建时才使用：
```bash
python3 scripts/migrate_data_center_postgres_to_mysql.py --execute --replace-target
```
迁移会保留记录 UUID、创建/更新时间、软删除状态和数据变更审计，从而避免实体引用失效；不会修改 PostgreSQL 源数据，也不会操作 FalkorDB 或知识图谱。
## 权限模型
一条接口策略包含：
1. 客户端（电脑、应用、合作方或设备）；
2. 数据库；
3. 数据表或全部表；
4. `metadata/read/create/update/delete` 动作；
5. 可读字段与可写字段；
6. 可选的行级 JSON 范围，例如 `{"district":"荔波县"}`；
7. 启用/停用状态。
接口客户端无法访问 `platform_control`、MySQL 系统库或其他业务数据库，也不能通过 API 执行 SQL。每次接口调用都会记录客户端、动作、资源范围、状态码、耗时和来源 IP。
docs/markitdown-evaluation.md
-82
View File
@@ -1,82 +0,0 @@
# MarkItDown 转换评测方法
本项目已经接入 Microsoft MarkItDown，但上线判断不能只看“能不能转”。推荐用一组真实业务样本文档做可重复评测。
## 评测维度
1. 转换成功率：不同格式是否稳定返回 Markdown。
2. 信息保真度：关键字段、价格、日期、地点、人名、产品 ID 是否还在。
3. 结构保留度：标题、表格、列表、链接是否保留为 Markdown 结构。
4. 噪声控制：乱码、超长行、残留 HTML、空文本、重复内容是否明显。
5. 下游效果：把转换后的 Markdown 送入知识抽取后，实体、关系、证据覆盖是否提升。
## 准备样本
把测试文件放到：
```bash
data/markitdown_eval/input/
```
建议每类至少 5 份：
- PDF：普通 PDF、扫描 PDF、复杂表格 PDF
- Word：合同、行程单、产品说明
- Excel：价格表、团期表、资源表
- PPT：介绍资料、图文页
- HTML/Markdown/CSV/JSON/XML
- 图片或截图类资料
## Manifest 示例
创建 `data/markitdown_eval/manifest.json`：
```json
{
"cases": [
{
"case_id": "travel_product_docx_001",
"file": "travel_product.docx",
"must_terms": ["产品ID", "成人价", "儿童价", "费用包含", "退费政策"],
"forbidden_terms": ["�"],
"expected_headings_min": 2,
"expected_tables_min": 1,
"expected_lists_min": 3,
"expected_links_min": 0,
"min_chars": 800,
"notes": "旅行社产品说明 Word"
}
]
}
```
## 运行评测
```bash
python3 scripts/evaluate_markitdown_conversion.py \
--input-dir data/markitdown_eval/input \
--manifest data/markitdown_eval/manifest.json \
--output-dir outputs/markitdown_eval \
--fail-under 0.70
```
输出：
- `outputs/markitdown_eval/converted/*.markitdown.md`
- `outputs/markitdown_eval/markitdown_eval_report.json`
- `outputs/markitdown_eval/markitdown_eval_report.md`
## 判定建议
- 平均分 `>= 0.85`：可作为默认转换方案，但仍抽检复杂文件。
- `0.70 - 0.85`：可用，但要看缺失字段和结构损失，必要时加 OCR 或人工校正。
- `< 0.70`：不建议直接进入自动知识抽取，应启用替代方案。
## 进一步增强
当前接入是 MarkItDown 本地转换。若样本中大量是扫描 PDF、图片文字、复杂表格、音视频，建议再评估：
- MarkItDown OCR plugin
- Azure Document Intelligence
- Azure Content Understanding
- 针对旅行社/城市知识图谱的自定义后处理规则