Huly 升级平台版本后如何用 admin tool 执行 upgrade-workspace 迁移工作区

Huly 升级平台版本后如何用 admin tool 执行 upgrade-workspace 迁移工作区

【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform

自托管的 Huly 升级到新版本后，已有工作区里的数据仍停留在旧模型版本上，需要用仓库中的 admin tool（@hcengineering/tool包，对应 dev/tool 目录）执行upgrade-workspace命令，把工作区迁移到新版本。这篇文章基于仓库中的脚本与命令定义，说明版本升级后如何完成这次迁移，以及如何判断迁移成功。

upgrade-workspace 命令与参数

命令定义在 dev/tool/src/index.ts：

upgrade-workspace <name>

• <name>：工作区名（必填），工具会在账号数据库中按名字查找工作区。
• -f, --force：Force update，默认true。
• -i, --indexes：Force indexes rebuild，默认false。

实际的迁移逻辑在同文件的doUpgrade（第 380–432 行）：从账号数据库读取工作区及其状态信息，用prepareTools()返回的新模型版本version调用upgradeWorkspace执行迁移，然后依次完成三件事：

1. 通过updateWorkspaceInfo把工作区信息更新为event: upgrade-done、progress: 100，并写入当前version；
2. 向 Workspace 队列主题发送workspaceEvents.upgraded()事件；
3. 打印升级指标，并输出upgrade-workspace done。

如果账号数据库中找不到该名字的工作区，命令会抛出workspace <name> not found错误。

前提：先让新版平台跑起来

迁移前，平台本身需要先升级到新版本。dev docker compose 环境按 dev/readme.md 操作：

rush build rush bundle rush docker:build docker compose up -d --force-recreate

工具迁移到的目标版本由MODEL_VERSION决定：dev/tool/package.json 的bundle脚本通过--define:MODEL_VERSION在构建期把它编译进 bundle，取值来自common/scripts/show_version.js（即当前 checkout 的版本号）。这意味着仓库路径下必须用新版代码重新 bundle 后再执行迁移；docker 镜像路径下则要对应用对应版本的hardcoreeng/tool镜像。

主路径：在 dev/tool 目录执行 rushx upgrade

dev/tool/package.json 中定义了升级入口：

"upgrade": "rushx run-local upgrade-workspace -- $1", "upgrade-mongo": "rushx run-local-mongo upgrade-workspace -- $1"

即rushx upgrade <工作区名>会先执行run-local：内部先rush bundle --to @hcengineering/tool构建工具 bundle，注入环境变量后以node --expose-gc --max-old-space-size=18000 ./bundle/bundle.js运行upgrade-workspace。

run-local注入的环境变量指向 huly.local 的 dev docker compose 环境：

SERVER_SECRET=secret FULLTEXT_URL=http://localhost:4702 ACCOUNTS_URL=http://localhost:3000 TRANSACTOR_URL=ws://localhost:3332 STORAGE_CONFIG='datalake|http://huly.local:4030' HULYLAKE_URL=http://huly.local:8096 ACCOUNT_DB_URL=postgresql://root@huly.local:26257/defaultdb?sslmode=disable DB_URL=postgresql://root@huly.local:26257/defaultdb?sslmode=disable TELEGRAM_DATABASE=telegram-service REKONI_URL=http://localhost:4004 REGION_INFO='cockroach|CockroachDB' MODEL_VERSION=$(node ../../common/scripts/show_version.js) GIT_REVISION=$(git describe --all --long) QUEUE_CONFIG='localhost:19092'

实际执行：

cd dev/tool rushx upgrade <工作区名>

upgrade-mongo与它等价，区别只是环境变量指向本地 mongo 开发环境（mongodb://localhost:27017、MINIO_ENDPOINT=localhost）。

如果平台部署不在 huly.local compose 环境，不要直接沿用run-local的地址，需要按实际部署自己组装环境变量。仓库里的 tests/tool-local.sh 是一个现成示例，可把最后一段作为模板参考（mongo/cockroach 测试环境）：

export MODEL_VERSION=$(node ../common/scripts/show_version.js) export STORAGE_CONFIG="datalake|http://localhost:4030" export MONGO_URL=mongodb://localhost:27017 export DB_URL=postgresql://root@localhost:26257/defaultdb?sslmode=disable export ACCOUNT_DB_URL=postgresql://root@localhost:26257/defaultdb?sslmode=disable export ACCOUNTS_URL=http://localhost:3000 export TRANSACTOR_URL="ws://huly.local:3333,ws://huly.local:3332;;cockroach" export ELASTIC_URL=http://localhost:9200 export SERVER_SECRET=secret export QUEUE_CONFIG=localhost:19092 node ../dev/tool/bundle/bundle.js upgrade-workspace <工作区名>

Postgres 测试环境对应 tests/tool-pg.sh（数据库端口 5433、Elastic 端口 9201），用法相同。

可选路径：直接用 docker 运行 hardcoreeng/tool 镜像

镜像部署时，仓库提供了一行脚本 dev/upgrade.sh，原文如下：

docker run -ti -e SERVER_SECRET=secret \ -e MONGO_URL=mongodb://127.0.0.1:27017 \ -e MINIO_ENDPOINT=minio \ -e MINIO_ACCESS_KEY=minioadmin \ -e MINIO_SECRET_KEY=minioadmin \ --rm --network host \ hardcoreeng/tool node ./bundle upgrade

执行前需要把SERVER_SECRET、MONGO_URL、MINIO_*等环境变量改成与自己部署一致。注意--network host表示容器共享宿主机网络，因此mongodb://127.0.0.1:27017这类地址要求 mongo 在宿主机上可达；--rm会在退出后删除容器。

可选路径：恢复备份后顺带升级

工具的backup-restore命令带--upgrade选项（定义见 index.ts 第 891 行），触发后会调用同一个doUpgrade，且 force 与 indexes 都置为true。测试恢复脚本中的用法（tests/restore-cockroach.sh）：

./tool-cockroach.sh backup-restore ./sanity-ws sanity-ws --upgrade

这条路径服务于"先恢复旧备份、再升到新版本"的场景；如果只是版本升级后的常规迁移，用upgrade-workspace主路径即可。

结果验证

依据doUpgrade的实现，判断迁移是否完成：

• 控制台打印升级指标（metricsToString(..., 'upgrade', 60)的输出），最后一行是upgrade-workspace done；
• 账号数据库中该工作区的信息被更新：event: upgrade-done、progress: 100，version字段写入当前版本号；
• Workspace 队列主题上发出workspaceEvents.upgraded()事件。

如果控制台报workspace <name> not found，说明账号数据库里不存在这个名字的工作区，先核对传给命令的工作区名是否正确，再检查ACCOUNT_DB_URL/DB_URL是否指向了正确的账号数据库。

【免费下载链接】platformHuly — All-in-One Project Management Platform (alternative to Linear, Jira, Slack, Notion, Motion)项目地址: https://gitcode.com/GitHub_Trending/platform80/platform