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:
1 parent
81c4dcc5c4
commit
1b677b8762
1 file changed
+196
@@ -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)。
|
||||
Reference in new issue
Block a user