docs(update): 同事升级操作说明(面向操作员友好版)

跟 2026-08-24-runbook.md(面向工程师技术细节)的区别:
- 升级说明:3 步命令可复制粘贴、验证清单可逐项打勾、失败兜底列具体场景
- runbook:DDL 设计取舍、FK 顺序、事务行为细节

涵盖:
1. 一句话总结(3 段命令贴进终端跑完即可)
2. 适用场景表(哪些情况要做、哪些不用)
3. 前置要求(PG 版本 / pgcrypto 扩展 / 操作账号权限)
4. 三步执行(改连接变量 → 跑 schema → 跑 seed)
5. 验证清单(7 条 SQL 逐项打勾)
6. 失败兜底(schema / seed / 接口三类问题的修法)
7. 升级前后对比(22 张表 vs 17 张 / 新增哪些列)
8. 升级完后下一步 + 还要问老板的事
This commit is contained in:
admin committed 2026-08-24 17:56:15 +08:00
1 parent 81c4dcc5c4
commit 1b677b8762
1 file changed
+196
+196
View File
@@ -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)。