0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
79 lines
5.8 KiB
Markdown
79 lines
5.8 KiB
Markdown
<!-- 导航元信息: {"内容描述": "系统组成、启动停止、备份恢复、资源更新与排障入口", "使用场景": "日常启动/停止、备份恢复、更新资源、排障时", "使用要求": "运行形态或运维入口变化时"} -->
|
||
# 运行手册
|
||
|
||
> 新版 Muse（agent-example 单用户作者工作台）的日常运行、备份与排障入口。能力状态与边界见文末。
|
||
|
||
## 1. 系统组成
|
||
|
||
| 组件 | 位置 | 说明 |
|
||
|---|---|---|
|
||
| 作者工作台服务 | 本机 `muse 服务`（uvicorn 127.0.0.1:8080） | 唯一正式写入口；静态工作台随资源包发布 |
|
||
| 正式内容库 | infra（100.64.0.8:5433）PG 实例，库 `muse_migration_1fe755ea37684f9d926f3a0cb3e9c7f2` | 作品/章/正文/规则/样例权威；用途角色 muse_app/eval/maint 隔离 |
|
||
| 资源包 | `src/muse/资源/`（构建身份见 `工具/环境预检.py`） | 角色/操作/提示词/工作台前端 |
|
||
| 应用配置 | `配置/本机正式.toml`、`配置/本机维护.toml` | 非敏感实例配置由 Git 管理，不依附临时工作树；模板为 `配置/应用.example.toml` |
|
||
|
||
## 2. 启动与停止
|
||
|
||
```bash
|
||
# 从 agent-example 仓库根启动；先确认 8080 没有其他实例。
|
||
# 日志、凭据和文件资产放在工作树之外，不能随迁移草稿一起清理。
|
||
umask 077
|
||
nohup .venv/bin/python -m muse 服务 配置/本机正式.toml \
|
||
>> "$HOME/.local/share/muse/正式环境/服务日志.log" 2>&1 &
|
||
echo $! > "$HOME/.local/share/muse/正式环境/服务.pid"
|
||
|
||
# 健康
|
||
curl -s http://127.0.0.1:8080/health # {"status":"alive"}
|
||
curl -s http://127.0.0.1:8080/ready # 含数据库连通
|
||
|
||
# 停止：先核对记录的 PID 确为本机正式.toml 对应服务，再终止该 PID。
|
||
pid=$(cat "$HOME/.local/share/muse/正式环境/服务.pid")
|
||
ps -p "$pid" -o command=
|
||
# 人工核对后执行：kill "$pid"
|
||
```
|
||
|
||
浏览器访问 `http://127.0.0.1:8080`，用配置的口令文件登录。当前作者 ID 为 `1`，与正式库的 7 部作者作品一致；不得用模板的 `author-local` 替代。
|
||
|
||
### 配置与凭据恢复
|
||
|
||
- 版本化范围：`配置/本机正式.toml`、`配置/本机维护.toml` 保存非敏感配置及受控引用；仅创建文件不代表已经提交 Git。
|
||
- 本机受控根：`~/.local/share/muse/正式环境/`（目录 0700，凭据文件 0600）。三个数据库角色分别使用 `muse_app.连接.txt`、`muse_eval.连接.txt`、`muse_maint.连接.txt`；工作台使用 `工作台口令.txt`。
|
||
- infra 凭据副本：SSH `个人-minione-ubuntu-infra-4c16g120g`，目录 `/opt/infra/private/muse-agent-example/`。恢复时复制所需文件到本机受控根并核对权限；禁止输出凭据内容到日志或提交明文凭据。
|
||
- 正式连接仅使用 PG `100.64.0.8:5433`，带 `keepalives=1 keepalives_idle=15 keepalives_interval=5 keepalives_count=3`。Redis 与本项目无关。
|
||
- 原迁移目录中的库外原文、草稿和切换回执尚未找回。当前文件根是恢复后新建的目录，不代表原文件资产已恢复。
|
||
|
||
## 3. 备份与恢复
|
||
|
||
```bash
|
||
# 完整备份（数据库 + 当前配置声明的文件根）；输出目录必须全新。
|
||
# 备份客户端要求 pg_dump 17：`brew install libpq@17`（镜像源可用，keg-only），
|
||
# 执行时前置 PATH=/opt/homebrew/opt/libpq@17/bin:$PATH。项目自身 NOWAIT 取锁已提供
|
||
# 冲突保护，不再向 pg_dump 传 --lock-wait-timeout（PG17 客户端下会自杀）。
|
||
.venv/bin/python -m muse 数据维护 备份 配置/本机维护.toml <全新备份目录>
|
||
.venv/bin/python -m muse 数据维护 核对 <备份目录>
|
||
# 恢复必须使用明确指向全新空库的维护配置，不能覆盖正式库。
|
||
.venv/bin/python -m muse 数据维护 恢复 <新空库维护配置> <备份目录> --预期备份ID <backup_id>
|
||
```
|
||
|
||
服务器级备份：infra 容器原生 PG 17 `pg_dump`，以 `muse_maint` 执行；恢复后的数据库归档保存在 `/opt/infra/private/muse-agent-example/backups/`，本机副本在 `~/.local/share/muse/正式环境/数据库备份/`。数据库单独归档不等于包含库外文件的完整备份，`pg_restore --list` 和哈希一致也不等于完成恢复演练。
|
||
|
||
## 4. 资源与代码更新
|
||
|
||
改代码/技能/提示词后：`工具/构建资源包.py` 重建 → `工具/环境预检.py` 取新 resource_build_id → 更新应用配置 `发布身份` → 重启服务。
|
||
|
||
## 5. 排障
|
||
|
||
| 症状 | 处置 |
|
||
|---|---|
|
||
| 长连接被掐（Tailscale 空闲断连） | 连接串须含 `keepalives=1 keepalives_idle=15 keepalives_interval=5 keepalives_count=3`（守卫白名单已含） |
|
||
| 写请求 SCOPE_DENIED | 缺 Origin 头或来源不在 `允许来源`；浏览器正常访问即自带 |
|
||
| 工作台 404 资源不存在 | 资源包未随新身份重建/配置身份过期，按第 4 节处理 |
|
||
| 连接被拒 target_denied | 端点/参数/角色不属于获准实例；检查连接串与允许实例记录 |
|
||
| 章后任务「抽取提案」失败 `模型协议错误`，证据里输出 token 等于上限 | 该提供方通道的模型默认产出推理（如 Claude 经 chat-completions 的 `reasoning_content`），把输出上限吃满；改用 Messages 协议（`anthropic`）并声明 `thinking="off"`，实测网关会映射为 `{"type":"disabled"}` |
|
||
|
||
## 6. 能力状态与验证边界
|
||
|
||
R2 主体交付、历史数据处置和原测试/恢复结果统一见[R2 改造历史留痕](实现回顾/R2改造历史留痕.md)，本手册不再保存过程验收状态。该历史归档不代表当前部署健康、旧库所有写权限关闭、129 项功能全量验证或生产无缺陷。
|
||
|
||
日常操作使用前述稳定配置与受控入口；运行状态以当次检查为准，文学效果、协议替身、真实宿主与模型证据分别判断。恢复合同见[备份与恢复入口](系统架构/新版设计/迁移与验收.md#备份与恢复入口)，不把历史恢复摘要或新建文件根当作已找回原库外资产。
|