# Muse 2.0.0 单人版部署手册

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

## 一、拓扑:双栈独立

单人版是两套 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。

## 三、从零部署步骤

1. **出可运行 jar**(Dockerfile 只 COPY jar、不在容器内编译):
   `mvn -pl muse-server -am -Dmaven.test.skip=true clean package`
2. **备凭据**:`cp scripts/dev/solo-compose.env.example .env.solo`,按第二节填全。
3. **起栈**:`docker compose -f docker-compose.solo.yml --env-file .env.solo up -d --build`
4. **库 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 保证。
5. **菜单收口**:provision 后执行 `sql/solo/2026-07-08-disable-solo-governance-menus-postgres.sql`(隐藏市场治理/多用户相关菜单;幂等,回滚脚本见同目录 `restore-*`)。
6. **验活**:`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](../agent-specs/2026-07-07-2.0.0单人版改造-review.md) 清单执行: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 语义在小版本间都可能变,不跑验收直接升会静默打断生成或检索。