diff --git a/docs/update/升级说明.md b/docs/update/升级说明.md new file mode 100644 index 0000000..b8fc113 --- /dev/null +++ b/docs/update/升级说明.md @@ -0,0 +1,196 @@ +# 尚数网本体管理平台 · 数据库升级说明(同事版) + +> 适用:把任何在跑的老库升级到 **2026-08-24 版本**。 +> 配套脚本:[`2026-08-24-schema-migrate.sql`](2026-08-24-schema-migrate.sql) + [`2026-08-24-builtin-seed.sql`](2026-08-24-builtin-seed.sql)。 +> 技术细节见 [`2026-08-24-runbook.md`](2026-08-24-runbook.md)。 + +--- + +## 0. 一句话总结 + +```bash +# 改下面 4 个变量后,把 3 段命令贴进终端跑完即可 +export PGHOST=... PGPORT=... PGUSER=... PGDATABASE=... + +cd <项目仓库>/docs/update +psql -v ON_ERROR_STOP=1 -f 2026-08-24-schema-migrate.sql # Step 1: 建表/加列 +psql -v ON_ERROR_STOP=1 -f 2026-08-24-builtin-seed.sql # Step 2: 灌内置数据 +psql -c "SELECT count(*) FROM information_schema.tables WHERE table_schema='public';" # Step 3: 验证 +``` + +期望最后 SELECT 返回 `≥ 21`(实际 22)。 + +--- + +## 1. 适用场景 + +| 你的情况 | 要做这个升级吗? | +|---|---| +| 跑 Docker 镜像 **`crpi-yscq976uwza88qap.cn-shenzhen.personal.cr.aliyuncs.com/ssw188/ssw-ontology:1.0.0`** 起的新实例 | ❌ **不用做** —— 镜像启动时会自动跑 migrate + seed | +| 跑 Docker 镜像但**挂载了老的 `/data/pg` 数据卷** | ✅ **要做** —— 否则旧 schema 不兼容,启动会报 ALTER 失败 | +| 本机 `./run.sh` 连 workspace 老 PG | ✅ **要做** | +| 手动部署到生产 PG(不让服务自己建表) | ✅ **要做** | +| CI/烟测/重新建空库 | ❌ 用镜像自带就行 | + +**判断方法**:连上库后跑 `SELECT count(*) FROM function_types WHERE builtin_fn<>'';` —— 如果返回 4(4 个内置函数),库已经是新版;如果返回 0 或 4 个以下,就需要升级。 + +--- + +## 2. 前置要求 + +| 项 | 最低版本 | 检查命令 | +|---|---|---| +| PostgreSQL | 14+(15/16/17 都行) | `psql --version` | +| pgcrypto 扩展 | 任意版本(用于 bcrypt 默认密码) | `psql -c "SELECT * FROM pg_available_extensions WHERE name='pgcrypto';"` 应返回 1 行 | +| 操作账号 | 至少能 `CREATE EXTENSION`(一般是库的 owner 或 superuser) | `psql -c "SELECT current_user, session_user;"` | + +如果 pgcrypto 装不上(权限不足),跑 schema 脚本没事,但 builtin-seed 里默认密码那段会失败 —— **可以跳过**,不影响其他功能,事后让管理员手工 `CREATE EXTENSION pgcrypto` 即可。 + +--- + +## 3. 三步执行 + +### Step 1: 改连接变量 + +```bash +# 替换成你的实际连接信息 +export PGHOST=127.0.0.1 +export PGPORT=15432 +export PGUSER=ssw +export PGPASSWORD=ssw +export PGDATABASE=ssw-ontology + +# 先连一下确认能通 +psql -c "SELECT current_database(), current_user, version();" +``` + +### Step 2: 跑 schema 迁移 + +```bash +cd /path/to/ssw-ontology/docs/update +psql -v ON_ERROR_STOP=1 -f 2026-08-24-schema-migrate.sql +``` + +**这条做了什么**:在一个事务里建 22 张表 + 12 个索引,并给已有表补齐 12 个新列(`title_property` / `when_to_suggest` / `submission_criteria` / `shared_properties` / `parent_interface_id` 等),幂等可重复。 + +**耗时**:空库 ~3 秒,旧库(已有数据)~10 秒(取决于 objects 表大小)。 + +**成功标志**:末尾有 `COMMIT` + 两条 `SELECT` 返回 `table_count ≥ 21` / `missing_object_source = 0` / `missing_link_source = 0`。 + +**失败**:立刻停下,先看错误再决定**回滚**还是**修复后重跑**。 + +### Step 3: 跑内置种子 + +```bash +psql -v ON_ERROR_STOP=1 -f 2026-08-24-builtin-seed.sql +``` + +**这条做了什么**:幂等灌入平台内置元数据 —— 4 个 builtin 函数(mask_field_by_policy / compute_object_link_strength / compute_data_asset_value / derive_object_completeness)、6 个 builtin REST 端点、4 个内置主体(manager / connector / public / ingest)+ clearances + grants + 1 个对象类型「合作企业」+ 3 条 demo 实例 + 对象默认 L0 标记。 + +**成功标志**:末尾 6 条验证 SELECT 全部命中预期数字(4 / 6 / 4 / 5 / 14 / 3+)。 + +--- + +## 4. 验证清单(逐项打勾) + +跑完后**逐条**复制粘贴进 psql,结果必须对上: + +```sql +-- 表数 ≥ 21 +SELECT count(*) AS table_count + FROM information_schema.tables WHERE table_schema='public'; +-- 期望: table_count >= 21(实际 22) + +-- 内置函数 = 4 +SELECT count(*) FROM function_types WHERE builtin_fn<>''; +-- 期望: 4 + +-- 内置接口 = 6 +SELECT count(*) FROM interface_types WHERE builtin=TRUE; +-- 期望: 6 + +-- 内置主体 = 4 +SELECT count(*) FROM principals WHERE is_builtin=TRUE; +-- 期望: 4(manager / connector / public / ingest) + +-- 默认 grants ≥ 5 +SELECT count(*) FROM grants; +-- 期望: ≥ 5 + +-- demo 种子 ≥ 3 +SELECT count(*) FROM objects WHERE pk LIKE 'demo_%'; +-- 期望: ≥ 3(demo_self / demo_partner_a / demo_partner_b) + +-- 溯源列非空 +SELECT count(*) FROM objects WHERE source IS NULL; +SELECT count(*) FROM links WHERE source IS NULL; +-- 期望: 都是 0 +``` + +**全部对上就完事了。** 把结果贴回群里给老板看。 + +--- + +## 5. 失败怎么办 + +### 5.1 schema 跑一半挂掉 + +脚本是事务,失败会自动回滚。**重跑前先看错误**: + +| 错误信息 | 原因 | 修法 | +|---|---|---| +| `permission denied for table ...` | 当前用户权限不足 | 换库 owner / superuser 重跑 | +| `relation "..." already exists` | 之前手动建过同名表 | 排查:别人手改过 schema?把对应表 DROP 掉再重跑,或直接 `DROP SCHEMA public CASCADE; CREATE SCHEMA public;`(⚠️ 会清掉所有数据) | +| `cannot add NOT NULL column without default` | 旧库该列已有数据但不允许 NULL | 用 `ADD COLUMN ... DEFAULT ''` 重新跑(脚本已用 `DEFAULT ''`) | + +### 5.2 builtin-seed 跑挂 + +`INSERT ... ON CONFLICT` 全部幂等,重复跑只更新已有行。最常见两个坑: + +| 错误 | 修法 | +|---|---| +| `function gen_salt(unknown, integer) does not exist` | pgcrypto 没装:`CREATE EXTENSION pgcrypto;` 然后重跑 | +| `duplicate key value violates unique constraint` | 不会发生(脚本都 ON CONFLICT),如果出现说明数据被外部改动过,把对应记录删掉再跑 | + +### 5.3 跑完后业务接口报错 + +最可能:前端缓存了旧 schema。**让同事强制刷新浏览器**(Cmd+Shift+R)或重启本体服务。 + +如果还报错:把浏览器报错截图 + `psql -c "SELECT ..."` 结果贴回群里。 + +--- + +## 6. 升级前后对比 + +| 维度 | 升级前 | 升级后 | +|---|---|---| +| 表 | 17 张 | **22 张**(+ materializations / materialization_rows / backing_sources / ontology_audit_log / access_log / link_properties) | +| `object_types` 新列 | 只有基础 | + `title_property` / `subtitle_property` / `color` / `primary_key` | +| `properties` 新列 | 只有基础 | + `format` / `default_value` / `indexable` / `vector_index` / `backing_column` | +| `action_types` 新列 | 只有基础 | + `submission_criteria` / `side_effects` / `impl_function_id` / `return_type` / `when_to_suggest` | +| `interface_types` 新列 | 只有基础 | + `shared_properties` / `parent_interface_id` | +| `function_types` 新列 | 已有 builtin_fn | + `when_to_suggest` / `llm_tool_description` | +| `link_types` 新列 | 已有 4 个 | + `directional` / `source_property` / `target_property` | +| `objects.source` 列 | 无 | **新增**(溯源,标记这条对象从哪个文件/连接器/AI 摄取导入的) | +| `links.source` 列 | 无 | **新增**(同 objects.source) | +| 访问控制 5 表 | 部分缺失 | **完整**(principals / principal_clearances / object_markings / grants / field_policies) | +| builtin functions | 缺失 | **4 个**(脱敏/链接强度/数据资产估值/完整度) | +| builtin interfaces | 缺失 | **6 个**(list_object_types / list_objects / get_object / search_ontology / get_facets / query_related) | +| demo 种子 | 无 | **3 条**(合作企业 + 示例·自营组织/合作伙伴 A/合作伙伴 B) | + +--- + +## 7. 升级完后下一步 + +1. **重启本体服务**(如果之前在跑):让内存里的缓存失效。 +2. **浏览器硬刷新**(Cmd+Shift+R / Ctrl+F5):清前端缓存。 +3. **测一下登录**:用内置主体登录(账号 `manager` / 密码 `dev1234`,这是 dev 默认;生产请改成强密码并写进 `.env` 的 `DEFAULT_BUILTIN_PASSWORD`)。 +4. **跑一遍连接器**:`curl http://127.0.0.1:8081/api/v1/connector/object-types | jq .count` 应返回 ≥ 1(合作企业)。 + +--- + +## 8. 还要问老板的事 + +- [ ] **改默认密码**:`manager` / `connector` / `public` / `ingest` 这四个内置账号的初始密码都是 `dev1234`,**生产必须改**。改法:在管理界面"账号管理"页直接改,或用 psql 跑 `UPDATE principals SET password_hash = crypt('新密码', gen_salt('bf', 10)) WHERE name='manager';` +- [ ] **删 demo 种子**:演示结束后在管理界面"实例管理 → 合作企业"勾选 3 条 demo 一键删除。 +- [ ] **AI 摄取**:要不要启用 AI 智能抽取?需要 `-e AI_ENABLED=true -e AI_BASE_URL=... -e AI_KEY=... -e AI_MODEL=...` 4 个环境变量(详见项目 README)。 \ No newline at end of file