From 071745d948d919bbdcf0282bdc747fe2bfd8432b Mon Sep 17 00:00:00 2001 From: ila Date: Thu, 20 Aug 2026 22:54:02 +0800 Subject: [PATCH] docs: document isolated MySQL 8 workflow (#5) --- docs/04-local-development-and-verification.md | 52 ++++++++++++++----- 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 3124ab8..44517d6 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Local-Development-and-Verification.- -wiki_revision: 4cb7c477267bfc28c8582e275e02e20acfc2c83e -synchronized_at: 2026-08-20T07:01:16Z +wiki_revision: c5dd8e3415c206839b1252ae32c61f48bdb21198 +synchronized_at: 2026-08-20T14:51:55Z # 本地开发与验证 @@ -23,7 +23,7 @@ synchronized_at: 2026-08-20T07:01:16Z | pnpm | 9.15.1，由 packageManager/Corepack 固定 | `pnpm --version` | | Tailwind | standalone，仅 portal 样式 | `tailwindcss --help` | -2026-08-20 盘点：本机 Go 1.23.0、MySQL 5.7.38、未安装 migrate，不能用于产品构建或迁移验收；Node 22.22.1 可用，但当前全局 pnpm 11.21.0，应按 admin-ui 的 `packageManager` 使用 pnpm 9.15.1。升级环境必须单独完成，不伪造验证结果。 +2026-08-20 已完成 MVP-0 环境基线：便携 Go 1.26.5、golang-migrate v4.19.1 和隔离 MySQL 8.4.8 已验证。Chorus 专用实例监听 `127.0.0.1:3308`，使用独立数据目录和测试账号；既有 `3307` 实例与 MySQL 5.7 不受影响。Node 22.22.1 可用；admin-ui 后续仍必须按 `packageManager` 使用 pnpm 9.15.1，不能直接采用全局 pnpm 11。 固定来源： @@ -56,21 +56,49 @@ $env:GITEA_URL = "https://git.ilapage.cn" python dev_scripts/harness.py sync --check ``` -### 2. 准备隔离数据库（产品代码落地后） +### 2. 进入固定工具环境并连接隔离数据库 -创建两个无生产数据的库：一个跑应用迁移测试，一个用于 go-admin 结构研究/代码生成。两者不得指向共享或生产实例。 +工具和凭据都位于仓库外。以下占位路径由维护者替换为自己的本机工具目录；环境文件不得提交，也不得把展开后的 DSN 输出到终端、日志、工单或 Wiki。 ```powershell -mysql -u root -p -e "CREATE DATABASE chorus_test DEFAULT CHARSET utf8mb4;" -mysql -u root -p -e "CREATE DATABASE chorus_codegen DEFAULT CHARSET utf8mb4;" -$env:CHORUS_DSN = "user:pass@tcp(127.0.0.1:3306)/chorus_test?parseTime=true&charset=utf8mb4" -migrate -path migrations -database "" up -migrate -path migrations -database "" down -migrate -path migrations -database "" up +$tools = "<本机工具目录>" +$env:PATH = "$tools\go1.26.5\bin;$tools\migrate-v4.19.1;$env:PATH" +. "$tools\chorus-test.env.ps1" + +go version +migrate -version +mysql --version ``` -连接串格式必须按 golang-migrate 的 MySQL driver 验证，不把 GORM DSN 直接拼成未经验证的 URL。每个迁移先 up、down、再 up；从空库重放全部迁移才算通过。 +当前已验证变量包括 `CHORUS_MYSQL_HOST`、`CHORUS_MYSQL_PORT`、`CHORUS_MYSQL_DATABASE`、`CHORUS_MYSQL_USER`、`CHORUS_MYSQL_PASSWORD`、`CHORUS_DB_DSN` 和 `CHORUS_MIGRATE_URL`。应用使用 GORM DSN，迁移工具使用单独验证过的 MySQL URL，不在两种格式之间临时拼接。 +专用实例的可复制启动和停止方式如下；`my.ini` 必须绑定 `127.0.0.1`，并指定独立端口、数据目录、日志和 PID 文件。 + +```powershell +$mysqlHome = "" +$instance = "" +Start-Process -FilePath "$mysqlHome\bin\mysqld.exe" ` + -ArgumentList "--defaults-file=$instance\my.ini", "--console" ` + -WindowStyle Hidden + +$env:MYSQL_PWD = $env:CHORUS_MYSQL_ROOT_PASSWORD +& "$mysqlHome\bin\mysqladmin.exe" --protocol=tcp ` + --host=127.0.0.1 --port=3308 --user=root shutdown +$env:MYSQL_PWD = $null +``` + +能力探测使用构造查询，不创建业务表： + +```powershell +$env:MYSQL_PWD = $env:CHORUS_MYSQL_PASSWORD +mysql --protocol=tcp --host=$env:CHORUS_MYSQL_HOST ` + --port=$env:CHORUS_MYSQL_PORT --user=$env:CHORUS_MYSQL_USER ` + --database=$env:CHORUS_MYSQL_DATABASE ` + --execute="START TRANSACTION; SELECT id FROM (SELECT 1 AS id) AS capability_probe FOR UPDATE SKIP LOCKED; ROLLBACK;" +$env:MYSQL_PWD = $null +``` + +业务迁移落地后，每个迁移必须在该隔离库执行 up、down、再 up，并从空库重放全部迁移。`chorus_codegen` 只在 MVP-1 的 go-admin 结构研究/代码生成工单中另行创建，不提前扩大当前账号权限。 ### 3. go-admin schema-first 生成（MVP-1） 1. 先在 `chorus_codegen` 执行同一套版本化 SQL。