chore: 一键检查、发布脚本与开发环境约定

- deno task test:all(scripts/test-all.sh):逐包跑完再汇总,连不上测试库直接失败, web 用 Node 跑 vitest;deno task ci 改用它 - deno task release(scripts/release.sh):工作区不干净、CHANGELOG 无本版条目即拒绝; 打 tag、构建、只替换 app、核对健康接口版本 - deno task dev:up:起开发库并迁移到最新;开发 API 端口改 4390(4380 留给本机部署版) - CLAUDE.md:命令、提交与发布约定、文档放哪 Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-02 16:08:09 +08:00
1 parent ceb66f8c77
commit 11ca2f01ff
@@ -147,9 +147,16 @@ docker compose --env-file .env.deploy logs app | grep 'setup token'
 本次整理来源功能增加 `scanOrganizeSource@1` 和迁移 `0059_organize_source_snapshot`，沿用 `verifyAndImport`。迁移不会扫描或整理已有目录；用户新增来源后先建立基线，存量必须单独触发。


+本机测试环境的标准做法:
+
 ```sh
 cd <仓库> && git pull
-docker compose --env-file .env.deploy exec app umt backup                              # 升级前先备份
+deno task release            # 工作区须干净、CHANGELOG 已有本版条目;打 tag → 构建 → 只替换 app → 核对健康版本
+```
+
+`scripts/release.sh --no-build` 用已有镜像只重建容器。真有要保留的数据时,先 `docker compose --env-file .env.deploy exec app umt backup` 再发布。手动等价命令:
+
+```sh
 docker compose --env-file .env.deploy up -d --build app                                # 重建镜像并替换容器;启动时自动迁移
 docker compose --env-file .env.deploy ps && docker compose --env-file .env.deploy logs --tail=50 app
 ```
@@ -312,7 +319,7 @@ API Key 在 qB 5.2+ WebUI 选项 → WebUI → API Key 处生成 / 轮换(等价

 ## v0.3.10 发布补充

-2026-10-01 已发布 v0.3.10，执行 `0060_manual_acquisition`：`acquisition_plan.slot_id` 允许为空，支持独立手动下载；`download_task.import_plan_id` 保存本次入库规划，并以外键引用计划。部署前备份与校验通过，只替换 app 容器；线上接口、版本一致及页面冒烟通过。后续普通 Compose 启动使用已更新的 `.env.deploy` 版本与源码标记。具体证据见 [发布记录](../plan/18-organize-release.md#v0310-手动下载与入库发布)。
+2026-10-01 已发布 v0.3.10，执行 `0060_manual_acquisition`：`acquisition_plan.slot_id` 允许为空，支持独立手动下载；`download_task.import_plan_id` 保存本次入库规划，并以外键引用计划。部署前备份与校验通过，只替换 app 容器；线上接口、版本一致及页面冒烟通过。后续普通 Compose 启动使用已更新的 `.env.deploy` 版本与源码标记。具体证据见 发布记录（已删除，见 git `ceb66f8`）。

 ### 当前测试入口

@@ -320,4 +327,4 @@ API Key 在 qB 5.2+ WebUI 选项 → WebUI → API Key 处生成 / 轮换(等价

 ## v0.3.11 修复发布

-搜索结果标题接入已有资源详情抽屉，已发布 v0.3.11；数据库保持 `0060`。浏览器桌面修复镜像为 `umt-browser-desktop:1.18.0-umt.1`，内置有效的最大化配置，已验证上下黑边消失。`.env.deploy` 已记录当前应用版本、源码标记和浏览器镜像，4380 HTTPS／443 HTTPS／本机 4381 HTTP 映射保留。具体验证见 [发布记录](../plan/18-organize-release.md#v0311-搜索详情与桌面黑边修复)。
+搜索结果标题接入已有资源详情抽屉，已发布 v0.3.11；数据库保持 `0060`。浏览器桌面修复镜像为 `umt-browser-desktop:1.18.0-umt.1`，内置有效的最大化配置，已验证上下黑边消失。`.env.deploy` 已记录当前应用版本、源码标记和浏览器镜像，4380 HTTPS／443 HTTPS／本机 4381 HTTP 映射保留。具体验证见 发布记录（已删除，见 git `ceb66f8`）。
@@ -3,16 +3,15 @@
 ## 前置

 - Deno 2.9.7(锁定;`curl -fsSL https://deno.land/install.sh | sh -s v2.9.7`)、Docker。不需要 Node.js / pnpm。
- 端口:web 5180、API 4380、PG 55433。本机 3000/5175/5176/55432 已被其他项目占用,不要改用。
+- 端口:web 5180、API 4390、PG 55433。4380 留给本机部署版(Caddy),本机 3000/5175/5176/55432 已被其他项目占用,不要改用。

 ## 首次启动

 ```sh
 cp .env.example .env          # 按需修改;server 与 db 脚本都读仓库根 .env
-deno task db:up               # 起 postgres:16-alpine(docker-compose.dev.yml,数据卷 umt-pg-data)
 deno install                  # 按 deno.lock 装依赖到 node_modules(成员包软链到 node_modules/@umt/*)
-deno task db:migrate          # 执行 packages/db/migrations 下全部迁移
-deno task dev                 # 同时起 server(4380)与 web(5180)
+deno task dev:up              # 起开发库 postgres:18.6(docker-compose.dev.yml)并迁移到最新;拉代码后也跑一次
+deno task dev                 # 同时起 server(4390)与 web(5180)
 ```

 单独起:`deno task dev:server`(`deno run --watch`,默认 `--role all`,API + worker 同进程)、`deno task dev:web`。
@@ -20,13 +19,13 @@ deno task dev                 # 同时起 server(4380)与 web(5180)
 ## 验证

 ```sh
-curl localhost:4380/api/v1/health
+curl localhost:4390/api/v1/health
 # 开发模式可用 .env 的 DEV_ADMIN_KEY 作 admin
-curl -N -H "Authorization: Bearer umt-dev-admin-key" "localhost:4380/api/v1/events?after=0"          # SSE 流(控制台用)
-curl -H "Authorization: Bearer umt-dev-admin-key" "localhost:4380/api/v1/events?after=0&limit=50"   # JSON 补读页(API Key 调用者用)
+curl -N -H "Authorization: Bearer umt-dev-admin-key" "localhost:4390/api/v1/events?after=0"          # SSE 流(控制台用)
+curl -H "Authorization: Bearer umt-dev-admin-key" "localhost:4390/api/v1/events?after=0&limit=50"   # JSON 补读页(API Key 调用者用)
 ```

- OpenAPI:http://localhost:4380/api/openapi.json,文档页 http://localhost:4380/api/docs
+- OpenAPI:http://localhost:4390/api/openapi.json,文档页 http://localhost:4390/api/docs
 - 控制台:http://localhost:5180,右上角钥匙按钮设置 API Key(存 localStorage `umt-api-key`)

 ## 常用命令