lili 1c2d51bfd4 feat(deploy): S9 单人版 compose 从零部署+黄金旅程活体验收(1a 闭合)

- docker-compose.solo.yml:muse-server 单体+PG+Redis 一体化编排,固化 sql/muse Flyway 迁移只读挂载(mini-infra 从零真验暴露漏挂致 muse 表全缺、AI worker 每秒报 relation does not exist)
- 2.0.0-单人版部署手册.md:双栈拓扑/凭据清单/从零步骤/回滚恢复多用户/Dify 升级约定
- 进度总账:§9 判据 0–7 全留证(黄金旅程 workId98 七步 PG 核验+compose 从零 36 迁移 121 表)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-07-08 10:19:47 -07:00

4.9 KiB

Raw Blame History

Muse 2.0.0 单人版部署手册

版本 v0.1 · 2026-07-08 · 读者:部署与运维者 · 边界:仅覆盖单人版(1a)从零部署与回滚;设计意图见 review v0.2,任务拆解见 execution。

一、拓扑:双栈独立

单人版是两套 compose 各自独立、通过网络互访,不合并成一个编排:

本栈(muse-cloud/docker-compose.solo.yml):muse-server 单体 + PostgreSQL + Redis。三者同网络,muse-server 经服务名 postgres/redis 直连;仅 muse-server 的 48080 对外暴露。
Dify 栈:沿用 Dify 官方 compose 独立部署(见 Dify 官方文档),提供写作/解析 chat app 与知识 dataset 检索。本栈通过 env 指向 Dify 的 base-url 与两类 key,不反向依赖。

这样切分的理由是:Dify 有自己的版本节奏与官方编排,合并会把它的升级风险耦合进 muse 主栈;独立后各自可单独重启、单独升级。

二、凭据清单

部署前准备下列值,写入 muse-cloud/.env.solo(从 scripts/dev/solo-compose.env.example 复制骨架;该样例只带开关默认值、不带真实凭据):

变量	含义	来源
`MUSE_POSTGRES_PASSWORD`	本栈 PG 密码	部署者自定,生产必须显式设置
`MUSE_REDIS_PASSWORD`	本栈 Redis 密码	部署者自定,生产必须显式设置
`MUSE_AI_DIFY_BASE_URL`	Dify chat app 入口(`.../v1`)	Dify 部署地址
`MUSE_AI_DIFY_WRITING_APP_ID` / `_API_KEY`	写作 chat app 与其 Service key	Dify 控制台该 app
`MUSE_AI_DIFY_PARSER_APP_ID` / `_API_KEY`	全书解析 chat app 与其 Service key	Dify 控制台该 app
`MUSE_KNOWLEDGE_DIFY_BASE_URL`	Dify 知识 dataset 入口(`.../v1`)	Dify 部署地址
`MUSE_KNOWLEDGE_DIFY_DATASET_API_KEY`	Dify dataset key(与 app key 不可混用)	Dify 控制台知识库 API

credentialRef(如 dify-writing-s1/dify-parser-s1)只是引用名、非密钥,已在 solo-compose.env.example 固定,须与注入的 Dify 凭据 ref 一致。app key 与 dataset key 是两套体系,混用会 401。

三、从零部署步骤

出可运行 jar(Dockerfile 只 COPY jar、不在容器内编译): mvn -pl muse-server -am -Dmaven.test.skip=true clean package
备凭据:cp scripts/dev/solo-compose.env.example .env.solo,按第二节填全。
起栈:docker compose -f docker-compose.solo.yml --env-file .env.solo up -d --build
库 provision(自动):PostgreSQL 空卷首次初始化时,docker-entrypoint-initdb.d 自动执行 sql/dev/yudao-base-*-postgres.sql 建 yudao 基座;muse-server 启动时 Flyway 跑 sql/muse/ 里 36 个脚本(V1..V37)建 muse 业务表。关键:sql/muse/ 经 compose 只读挂载到容器 /muse-server/sql/muse(flyway.locations 含 filesystem:sql/muse),脚本未打进 jar——部署目录必须含 sql/muse/,漏挂则 Flyway "No migrations found"、muse 表全缺、AI worker 每秒报 relation does not exist(mini-infra 从零真验暴露并已在 compose 固化挂载)。二者顺序由 depends_on healthcheck 保证。
菜单收口:provision 后执行 sql/solo/2026-07-08-disable-solo-governance-menus-postgres.sql(隐藏市场治理/多用户相关菜单;幂等,回滚脚本见同目录 restore-*)。
验活:curl --noproxy '*' http://<host>:48080/app-api/muse/...(app-api 固定带 tenant-id: 1)。

无 Nacos 环境已在 compose 内以 SPRING_CLOUD_NACOS_DISCOVERY_ENABLED=false 关闭服务发现,启动日志不应有注册中心持续重连噪声。

四、回滚与恢复多用户

部署层回滚是独立的:docker compose -f docker-compose.solo.yml down(加 -v 清库卷则回到全新)。代码层不受影响。

若日后要恢复多用户形态(市场/成员),不是「取消一行 pom 注释」,按 review v0.2 §10 清单执行:muse-server pom 取消 market-server 注释 → 激活 market-assembled maven profile(回编译被排除的市场测试树、修排除期漂移) → 覆盖门 market 域退出 dormant → 前端 revert 裁剪 → 部署库执行 restore-solo-governance-menus 恢复菜单 → 成员子域打开对应 enabled 开关。RAGFlow 运行时已在 S6d 删除(git 可回),恢复需按新集成重走契约与验收,不承诺兼容。

五、Dify 版本升级约定

Dify 是单人版唯一新增外部服务,且承载生成与知识两条主链。升级 Dify 版本前必须先在隔离环境跑 live 验收:P1rDifyChatLiveAcceptanceIT + P1rDifyDatasetsContractLiveIT(MUSE_P1R_EXTERNAL_ACCEPTANCE=true)+ 本手册第三节的黄金旅程 smoke,全绿后再升生产。Dify 的 console CSRF、per-tenant RSA 凭据加密、chat/dataset 两套 key 语义在小版本间都可能变,不跑验收直接升会静默打断生成或检索。

4.9 KiB Raw Blame History