OPC/lexgo
2
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 同步 #15 交付页与本地开发页镜像 (#15)

Browse Source 
docs/04 与线上 Wiki 的纯二进制安装与交叉验证记录保持一致，revision fa4c663fabf5db418104fc53b7ce00f41f5ba910。
This commit was merged in pull request #35.
This commit is contained in:
ila
2026-09-15 17:12:02 +08:00
parent 420365fc6b
commit dde2ac127a
1 changed files with 188 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/04-local-development-and-verification.md
+188 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
wiki_page: Local-Development-and-Verification
wiki_url: https://git.ilapage.cn/OPC/lexgo/wiki/Local-Development-and-Verification.-
wiki_revision: caa80888cf42fd7fd7f040e9fe1147203fe7bfe3
synchronized_at: 2026-09-15T08:27:38Z
wiki_revision: fa4c663fabf5db418104fc53b7ce00f41f5ba910
synchronized_at: 2026-09-15T09:11:27Z
<!-- gitea-wiki-mirror:end -->
# 本地开发与验证
@@ -560,3 +560,189 @@ node --test spikes/english/view.test.mjs
- 未做定时备份、监控与告警；备份与恢复均为人工触发。
- 大库恢复耗时与磁盘空间上限未测；演练库与生产库规模不同。
- 附件（封面/音频，#21）尚未实现，恢复范围目前只覆盖数据库。
## #15 交付、备份与恢复验证（2026-09-15）
本单**无 schema 变化、无迁移**：新增运维脚本、部署文档与演练证据。所有命令在仓库根执行；MySQL 客户端用 8.4（`LEXGO_MYSQL_BIN=D:/mysql843/bin`），因为本机 PATH 上是 5.7 客户端，`install-check` 会把它判为不达标。
### 运维命令
纯二进制路径（部署机不需要 Python）：
| 用途 | 命令 |
|---|---|
| 迁移 / 初始化管理员 | `./lexgo migrate` / `./lexgo bootstrap` |
| 备份 | `./lexgo backup --out <目录>` |
| 恢复到空库 | `./lexgo restore --dump <备份.sql.gz> --database <库名> --confirm` |
| 校验 | `./lexgo verify --database <库名> [--manifest <manifest.json>]` |
工具通道（开发便利与交叉验证）：
| 用途 | 命令 |
|---|---|
| 依赖与资源检查 | `python scripts/ops.py install-check` |
| 建空库并提示权限 | `python scripts/ops.py init-database --database <库名>` |
| 备份 | `python scripts/ops.py backup --out <目录>` |
| 恢复到空库 | `python scripts/ops.py restore --dump <备份.sql.gz> --database <库名> --confirm` |
| 校验（数据完整性，可选接口闭环） | `python scripts/ops.py verify --database <库名> [--manifest <manifest.json>] [--api http://127.0.0.1:<端口> --user <前缀> --password-env <变量名>]` |
| 干净实例两账号闭环演练 | `python scripts/ops.py smoke --api <url> --admin-user <账号> --user <前缀>` |
| 性能测量 | `python scripts/bench.py --database <库名> --api <url> --user <账号>` |
### 两条通道的交叉验证（2026-09-15，19 项检查全部通过）
Go 二进制与 Python 工具各做一次备份，并**互相恢复对方的备份**：
1. 两条通道的 `manifest.json` 字段齐备、逐表行数一致、`schema_version` 一致、都不含凭据字段；
2. Go 产出的 dump 由 Python 恢复成功，Python 产出的 dump 由 Go 恢复成功（`lexgo restore` 输出 `verified`）；
3. Go 校验 Go 恢复出来的库、Python 校验 Python 恢复出来的库，逐表行数与 manifest 一致；
4. 两个恢复实例的**逐表内容校验和都与源库一致**（13 张表），源库在过程中未被改动；
5. `lexgo verify` 可以直接校验源库；
6. 安全边界两条通道各自确认：Go 拒绝覆盖已有库、要求 `--confirm`，Python 拒绝系统库。
证据：`.local/issue15-crosscheck-evidence.json`。Go 侧另有 `TestMySQLOpsBackupRestoreRoundTrip` 集成用例（备份 → 恢复到空库 → 校验 → 拒绝二次覆盖 → 源库校验和不变）。
### 完整演练（2026-09-15，本机一次性通过，27 项顶层检查全部 `[ok]`）
演练脚本（`.local/tmp/issue15-drill.py`，一次性工具）依次执行：
1. **干净安装**：`init-database` 建空库 → `migrate`（schema v7，14 张表）→ 确认「新库没有账号、没有业务数据」→ `bootstrap` 建管理员 → **再次 `bootstrap` 被拒绝**（退出码 1，不覆盖管理员）→ 起独立 API 实例（:8010）。
2. **两个演练账号走通闭环**（`ops.py smoke`，19 项全过）：管理员建 `trial_a`/`trial_b` → 新账号书库与进度为空 → 粘贴章节 → 章节处理完成 → 分词返回可点选词 → 词典查询返回明确状态 → 保存词义 → 另一账号查不到该词条 → 新词立刻到期 → 作答成功 → 重复作答不重复记账 → 完成章节只记已读 → 进度反映活动；`B` 读 `A` 的书 404、书库仍为空。
3. **备份 lexgo_dev**（约 12 MB gz）：manifest 记录 schema 7、提交哈希、逐表行数、sha256；确认 manifest 无凭据字段；确认 dump 不含 `CREATE DATABASE`/`USE`（不会误写回源库）。
4. **恢复到空库** `lexgo_restore_drill` 并自动校验（33 项全过）：逐表行数与备份一致（`sys_user` 6、`books` 27、`chapters` 33、`terms` 13、`term_reviews` 13、`review_answers` 55、`login_logs` 192 等）→ **逐表内容校验和与源库一致**（13 张表）→ **源库 lexgo_dev 未被改动**。
5. **安全边界**：恢复默认拒绝覆盖已有库；拒绝写入系统库 `mysql`；不带 `--confirm` 直接拒绝。
6. **恢复实例的两账号闭环与越权校验**（`:8011`，41 项全过）——恢复后的账号仍可登录、词条与到期队列仍在、答题与完成章节保持幂等、`B` 无法读取或修改 `A` 的数据。
7. **收尾**：删除两个演练库，确认 `lexgo_dev` 与测试库保留，`lexgo_dev` 仍是 schema 7。
### 性能观察（`scripts/bench.py`，人造数据集，单机无并发）
数据集：1 个账号、20 本书 20 章（每章约 500 个词）、2000 词条、8000 条复习作答。环境：Windows 10（10.0.19044）、8 核、31.7 GB 内存、MySQL 8.4.3、Go 工具链由 `scripts/server.py` 固定为 1.26.5。
| 接口 | 请求数 | p50 | p95 | 最大 | 错误 |
|---|---|---|---|---|---|
| `POST /login` | 10 | 82.2 ms | 93.3 ms | 93.3 ms | 0 |
| `GET /books` | 30 | 5.9 ms | 18.1 ms | 18.2 ms | 0 |
| `GET /chapters/1` | 30 | 8.3 ms | 20.1 ms | 22.0 ms | 0 |
| `GET /chapters/1/tokens` | 30 | 10.0 ms | 23.6 ms | 30.3 ms | 0 |
| `GET /terms`（第 1 页） | 30 | 10.2 ms | 20.4 ms | 21.5 ms | 0 |
| `GET /terms?query`（搜索） | 30 | 12.3 ms | 24.9 ms | 27.0 ms | 0 |
| `GET /progress` | 30 | 15.7 ms | 26.1 ms | 29.1 ms | 0 |
| `GET /reviews/queue` | 30 | 22.7 ms | 32.3 ms | 34.2 ms | 0 |
**这些是观察值，不是容量承诺**：单机、单进程、无并发压力；登录接口每地址每分钟限 30 次，因此登录只测 10 次，该数字不代表登录吞吐。原始报告：`.local/issue15-bench.json`。
### 集成验证矩阵（复用既有 Go 测试，`LEXGO_TEST_DB_NAME=lexgo_test_issue13` 70 项全过）
| 验收要求 | 覆盖用例（全部通过） |
|---|---|
| 越权与隔离 | `TestMySQLLibraryIsolationAndOwnership`、`TestMySQLTermIsolationAndInputRules`、`TestMySQLPhraseRulesAndIsolation`、`TestMySQLReviewAnswerErrorsAndOwnership`、`TestMySQLAccountIsolationAndRevocation` |
| 任务崩溃重试 | `TestMySQLIngestRecoveryWithoutRestart`、`TestMySQLIngestRecoveryAfterRestart`、`TestMySQLIngestAttemptsAreBoundedAndManualRetryRestarts`、`TestMySQLRetryAfterContentRestoredPublishesSameChapter`、`TestMySQLRecoverySkipsSupersededJobs` |
| 并发答题与并发删除 | `TestMySQLReviewConcurrentReplayOfOneAnswer`、`TestConcurrentDuplicateAccountHasOneWinner`、`TestMySQLConcurrentChapterDelete`、`TestMySQLDeleteDuringProcessing` |
| 长文与输入上限 | `TestMySQLPasteRejectsInvalidInputAndLimits`、`TestMySQLTextUploadKeepsChapterLimit`、`TestMySQLTextUploadRejectsInvalidSubmissions`、`TestMySQLTextUploadRejectsInvalidSubmissions` |
| 迁移与回退标记 | `TestMigrationRefusesUnownedOrUnsupportedSchema`、`TestMigrationCanResumeOwnedPartialSchema`、全部 `TestMigrationFrom*` |
### 治理与其它测试
`python -m unittest discover -s tests` 65 项通过（新增 9 项 `tests/test_lexgo_ops.py`，不需要数据库）；`harness.py check --strict` 与 `sync --check` 通过。本单未改前端与后端业务代码，仍复跑 `LEXGO_TEST_DB_NAME=lexgo_test_issue13 python scripts/server.py test-integration` 70 项通过。
### 未验证
- **真实回滚（升级后切回旧二进制）未演练**：文档给出规则（迁移只新增对象，回退前写回版本号），但没有在真实实例上做过升级/回滚全过程。
- 未验证 HTTPS、域名、反代配置、多机与灰度；本机演练只在 `127.0.0.1` 上起两个临时实例。
- 未做定时备份、监控与告警；备份与恢复均为人工触发。
- 大库恢复耗时与磁盘空间上限未测；演练库与生产库规模不同。
- 附件（封面/音频，#21）尚未实现，恢复范围目前只覆盖数据库。
## #15 交付、备份与恢复验证（2026-09-15）
本单**无 schema 变化、无迁移**：新增运维脚本、部署文档与演练证据。所有命令在仓库根执行；MySQL 客户端用 8.4（`LEXGO_MYSQL_BIN=D:/mysql843/bin`），因为本机 PATH 上是 5.7 客户端，`install-check` 会把它判为不达标。
### 运维命令
纯二进制路径（部署机不需要 Python）：
| 用途 | 命令 |
|---|---|
| 迁移 / 初始化管理员 | `./lexgo migrate` / `./lexgo bootstrap` |
| 备份 | `./lexgo backup --out <目录>` |
| 恢复到空库 | `./lexgo restore --dump <备份.sql.gz> --database <库名> --confirm` |
| 校验 | `./lexgo verify --database <库名> [--manifest <manifest.json>]` |
工具通道（开发便利与交叉验证）：
| 用途 | 命令 |
|---|---|
| 依赖与资源检查 | `python scripts/ops.py install-check` |
| 建空库并提示权限 | `python scripts/ops.py init-database --database <库名>` |
| 备份 | `python scripts/ops.py backup --out <目录>` |
| 恢复到空库 | `python scripts/ops.py restore --dump <备份.sql.gz> --database <库名> --confirm` |
| 校验（数据完整性，可选接口闭环） | `python scripts/ops.py verify --database <库名> [--manifest <manifest.json>] [--api http://127.0.0.1:<端口> --user <前缀> --password-env <变量名>]` |
| 干净实例两账号闭环演练 | `python scripts/ops.py smoke --api <url> --admin-user <账号> --user <前缀>` |
| 性能测量 | `python scripts/bench.py --database <库名> --api <url> --user <账号>` |
### 纯二进制安装演练（2026-09-15，9 项检查全部通过）
不使用 Python 执行安装步骤：建空库 → `lexgo migrate`（v7，14 张表）→ 确认空库无账号 → `lexgo bootstrap` 建管理员 → **再次 bootstrap 被拒绝** → `lexgo verify` 通过 → `lexgo serve` 自身健康检查通过 → 两个演练账号走通学习闭环（19 项）→ 删除演练库。接口层的两账号闭环由工具通道驱动（它需要发 HTTP 请求），这一点在部署页已写明。证据：`.local/issue15-binary-drill-evidence.json`。
### 两条通道的交叉验证（2026-09-15，19 项检查全部通过）
Go 二进制与 Python 工具各做一次备份，并**互相恢复对方的备份**：
1. 两条通道的 `manifest.json` 字段齐备、逐表行数一致、`schema_version` 一致、都不含凭据字段；
2. Go 产出的 dump 由 Python 恢复成功，Python 产出的 dump 由 Go 恢复成功（`lexgo restore` 输出 `verified`）；
3. Go 校验 Go 恢复出来的库、Python 校验 Python 恢复出来的库，逐表行数与 manifest 一致；
4. 两个恢复实例的**逐表内容校验和都与源库一致**（13 张表），源库在过程中未被改动；
5. `lexgo verify` 可以直接校验源库；
6. 安全边界两条通道各自确认：Go 拒绝覆盖已有库、要求 `--confirm`，Python 拒绝系统库。
证据：`.local/issue15-crosscheck-evidence.json`。Go 侧另有 `TestMySQLOpsBackupRestoreRoundTrip` 集成用例（备份 → 恢复到空库 → 校验 → 拒绝二次覆盖 → 源库校验和不变）。
### 完整演练（2026-09-15，本机一次性通过，27 项顶层检查全部 `[ok]`）
演练脚本（`.local/tmp/issue15-drill.py`，一次性工具）依次执行：
1. **干净安装**：`init-database` 建空库 → `migrate`（schema v7，14 张表）→ 确认「新库没有账号、没有业务数据」→ `bootstrap` 建管理员 → **再次 `bootstrap` 被拒绝**（退出码 1，不覆盖管理员）→ 起独立 API 实例（:8010）。
2. **两个演练账号走通闭环**（`ops.py smoke`，19 项全过）：管理员建 `trial_a`/`trial_b` → 新账号书库与进度为空 → 粘贴章节 → 章节处理完成 → 分词返回可点选词 → 词典查询返回明确状态 → 保存词义 → 另一账号查不到该词条 → 新词立刻到期 → 作答成功 → 重复作答不重复记账 → 完成章节只记已读 → 进度反映活动；`B` 读 `A` 的书 404、书库仍为空。
3. **备份 lexgo_dev**（约 12 MB gz）：manifest 记录 schema 7、提交哈希、逐表行数、sha256；确认 manifest 无凭据字段；确认 dump 不含 `CREATE DATABASE`/`USE`（不会误写回源库）。
4. **恢复到空库** `lexgo_restore_drill` 并自动校验（33 项全过）：逐表行数与备份一致（`sys_user` 6、`books` 27、`chapters` 33、`terms` 13、`term_reviews` 13、`review_answers` 55、`login_logs` 192 等）→ **逐表内容校验和与源库一致**（13 张表）→ **源库 lexgo_dev 未被改动**。
5. **安全边界**：恢复默认拒绝覆盖已有库；拒绝写入系统库 `mysql`；不带 `--confirm` 直接拒绝。
6. **恢复实例的两账号闭环与越权校验**（`:8011`，41 项全过）——恢复后的账号仍可登录、词条与到期队列仍在、答题与完成章节保持幂等、`B` 无法读取或修改 `A` 的数据。
7. **收尾**：删除两个演练库，确认 `lexgo_dev` 与测试库保留，`lexgo_dev` 仍是 schema 7。
### 性能观察（`scripts/bench.py`，人造数据集，单机无并发）
数据集：1 个账号、20 本书 20 章（每章约 500 个词）、2000 词条、8000 条复习作答。环境：Windows 10（10.0.19044）、8 核、31.7 GB 内存、MySQL 8.4.3、Go 工具链由 `scripts/server.py` 固定为 1.26.5。
| 接口 | 请求数 | p50 | p95 | 最大 | 错误 |
|---|---|---|---|---|---|
| `POST /login` | 10 | 82.2 ms | 93.3 ms | 93.3 ms | 0 |
| `GET /books` | 30 | 5.9 ms | 18.1 ms | 18.2 ms | 0 |
| `GET /chapters/1` | 30 | 8.3 ms | 20.1 ms | 22.0 ms | 0 |
| `GET /chapters/1/tokens` | 30 | 10.0 ms | 23.6 ms | 30.3 ms | 0 |
| `GET /terms`（第 1 页） | 30 | 10.2 ms | 20.4 ms | 21.5 ms | 0 |
| `GET /terms?query`（搜索） | 30 | 12.3 ms | 24.9 ms | 27.0 ms | 0 |
| `GET /progress` | 30 | 15.7 ms | 26.1 ms | 29.1 ms | 0 |
| `GET /reviews/queue` | 30 | 22.7 ms | 32.3 ms | 34.2 ms | 0 |
**这些是观察值，不是容量承诺**：单机、单进程、无并发压力；登录接口每地址每分钟限 30 次，因此登录只测 10 次，该数字不代表登录吞吐。原始报告：`.local/issue15-bench.json`。
### 集成验证矩阵（复用既有 Go 测试，`LEXGO_TEST_DB_NAME=lexgo_test_issue13` 70 项全过）
| 验收要求 | 覆盖用例（全部通过） |
|---|---|
| 越权与隔离 | `TestMySQLLibraryIsolationAndOwnership`、`TestMySQLTermIsolationAndInputRules`、`TestMySQLPhraseRulesAndIsolation`、`TestMySQLReviewAnswerErrorsAndOwnership`、`TestMySQLAccountIsolationAndRevocation` |
| 任务崩溃重试 | `TestMySQLIngestRecoveryWithoutRestart`、`TestMySQLIngestRecoveryAfterRestart`、`TestMySQLIngestAttemptsAreBoundedAndManualRetryRestarts`、`TestMySQLRetryAfterContentRestoredPublishesSameChapter`、`TestMySQLRecoverySkipsSupersededJobs` |
| 并发答题与并发删除 | `TestMySQLReviewConcurrentReplayOfOneAnswer`、`TestConcurrentDuplicateAccountHasOneWinner`、`TestMySQLConcurrentChapterDelete`、`TestMySQLDeleteDuringProcessing` |
| 长文与输入上限 | `TestMySQLPasteRejectsInvalidInputAndLimits`、`TestMySQLTextUploadKeepsChapterLimit`、`TestMySQLTextUploadRejectsInvalidSubmissions`、`TestMySQLTextUploadRejectsInvalidSubmissions` |
| 迁移与回退标记 | `TestMigrationRefusesUnownedOrUnsupportedSchema`、`TestMigrationCanResumeOwnedPartialSchema`、全部 `TestMigrationFrom*` |
### 治理与其它测试
`python -m unittest discover -s tests` 65 项通过（新增 9 项 `tests/test_lexgo_ops.py`，不需要数据库）；`harness.py check --strict` 与 `sync --check` 通过。本单未改前端与后端业务代码，仍复跑 `LEXGO_TEST_DB_NAME=lexgo_test_issue13 python scripts/server.py test-integration` 70 项通过。
### 未验证
- **真实回滚（升级后切回旧二进制）未演练**：文档给出规则（迁移只新增对象，回退前写回版本号），但没有在真实实例上做过升级/回滚全过程。
- 未验证 HTTPS、域名、反代配置、多机与灰度；本机演练只在 `127.0.0.1` 上起两个临时实例。
- 未做定时备份、监控与告警；备份与恢复均为人工触发。
- 大库恢复耗时与磁盘空间上限未测；演练库与生产库规模不同。
- 附件（封面/音频，#21）尚未实现，恢复范围目前只覆盖数据库。