opt 目录结构深度治理方案

1. 现状全景

1.1 /opt 一级目录结构

1.2 Git 仓库分布

1.3 软链接全量清单

2. 核心问题诊断

2.1 问题一：/opt 根下的「影子目录」

7 个软链接让 /opt 根看起来有 14 个目录，实际只有 7 个实体。这造成：

• 路径歧义：有人写 /opt/sing-box，有人写 /opt/server/sing-box
• 维护困惑：修改 ./data 时不知道到底在哪个目录下
• 备份遗漏：容易以为 /opt/sing-box 是实体而漏掉 /opt/server/sing-box

2.2 问题二：financial-team 的「双重身份」

• /opt/agent/financial-team（软链接源）和 /opt/ywz-agent-ecosystem/agent/financial-team（git 跟踪）几乎同步但有差异
• scripts/ 目录只存在于前者
• .gitignore 只存在于后者
• docker-compose 挂载的是后者，运行时读取的是前者（通过软链接）

2.3 问题三：数据与代码混居

plugin-runtime-deps 是 openclaw 运行时下载的 node_modules，不应备份，但占了 11G。

2.4 问题四：脚本硬编码路径

agent-watchdog.sh 硬编码 REPO_ROOT=”/opt/ywz-agent-ecosystem”，如果目录结构变更会失效。

3. 治理原则

1. 实体优先：每个目录要么全是实体文件，要么明确标记为快捷方式
2. 代码与数据分离：运行时数据不混在代码目录里
3. 单一路径：同一个服务只有一个官方路径，消灭歧义
4. git 内聚：所有进 git 的代码在一个仓库里，或明确 submodule/subtree 关系
5. 低风险迁移：不改 docker-compose 的相对路径，不改 Caddy 端口映射

4. 分阶段治理方案

Phase 1：止血 + 小合并（当天可完成）

4.1.1 合并 CLAUDE.md（零风险）

cd /opt/vendor/openclaw-src
cp AGENTS.md CLAUDE.md
git add CLAUDE.md
git commit -m "chore: merge CLAUDE.md symlink into entity"

cd /opt/vendor/daily-stock-analysis
cp AGENTS.md CLAUDE.md
git add CLAUDE.md
git commit -m "chore: merge CLAUDE.md symlink into entity"

4.1.2 合并 backup.sh（低风险）

cp /opt/server/backup/vps-backup.sh /opt/server/scripts/backup.sh
# 删除软链接，替换为实体文件（已经是实体 copy）

4.1.3 统一 scripts 入口（中低风险）

/opt/scripts 和 /opt/server/scripts 是同一个目录。建议：

• 方案 A：删掉 /opt/scripts 软链接，所有脚本和配置统一用 /opt/server/scripts
• 方案 B：把 /opt/server/scripts move 到 /opt/scripts，然后删掉 server/scripts/

推荐 方案 A，因为 /opt/server/ 是实体分类目录，保留它更符合治理原则。

Phase 2：/opt 根扁平化（需停机窗口）

目标：删除 /opt 根下 7 个软链接，让 /opt 根只保留「顶级实体」。

4.2.1 迁移策略

4.2.2 为什么可以直接删

• docker-compose 的 volume 挂载用的是 ./data（相对 docker-compose.yml 所在目录），软链接不影响
• Caddy 反代用的是 localhost:port，不依赖文件路径
• 没有任何 systemd service 或 cron 使用 /opt/xxx 根的软链接路径（agent-watchdog 用的是 /opt/ywz-agent-ecosystem）

4.2.3 执行命令

cd /opt
rm -f junjun-claw ywzclaw matrix minio rustdesk scripts sing-box

风险：你日常操作的习惯路径会失效。建议先改 shell alias 或 bashrc。

Phase 3：代码与数据分离（长期）

4.3.1 plugin-runtime-deps 迁移

junjunclaw 和 ywzclaw 各 5.5G 的 plugin-runtime-deps 是运行时下载的，不应在 /opt/agent 下。

建议：

# 创建独立数据目录
mkdir -p /var/lib/openclaw/junjunclaw
mkdir -p /var/lib/openclaw/ywzclaw

# 迁移 plugin-runtime-deps（需停机）
mv /opt/agent/junjunclaw/data/plugin-runtime-deps /var/lib/openclaw/junjunclaw/
mv /opt/agent/ywzclaw/data/plugin-runtime-deps /var/lib/openclaw/ywzclaw/

# 创建软链接（反向：实体在新位置，链接在旧位置）
ln -s /var/lib/openclaw/junjunclaw/plugin-runtime-deps /opt/agent/junjunclaw/data/plugin-runtime-deps
ln -s /var/lib/openclaw/ywzclaw/plugin-runtime-deps /opt/agent/ywzclaw/data/plugin-runtime-deps

或者更彻底：修改 docker-compose 的 volume 挂载，把 plugin-runtime-deps 映射到外部目录。

4.3.2 Matrix pgdata 迁移

mkdir -p /var/lib/matrix
mv /opt/comm/matrix/pgdata /var/lib/matrix/
# 更新 docker-compose.yml 的 volume 挂载

4.3.3 建立 /opt 目录公约

治理后的 /opt 结构：

/opt/
├── agent/          # AI agent 部署（代码+配置）
│   ├── junjunclaw/
│   ├── ywzclaw/
│   └── financial-team/  ← 从 ywz-agent-ecosystem 分离后的独立目录
├── comm/           # 通信基础设施
│   └── matrix/
├── knowledge/      # 知识管理
│   ├── siyuan/
│   └── siyuan-junjun/
├── server/         # 通用服务器
│   ├── sing-box/
│   ├── minio/
│   ├── rustdesk/
│   ├── backup/
│   └── scripts/
├── vendor/         # 第三方源码（只读）
│   ├── openclaw-src/
│   ├── daily-stock-analysis/
│   └── 3x-ui-src/
├── vibecoding/     # 代码生成项目
│   ├── coding_com/
│   ├── rule/
│   └── worklog/
└── ywz-agent-ecosystem/  # 主生态仓库（代码+部署配置）

5. 执行清单（按优先级）

6. 风险与回滚

6.1 软链接删除回滚

如果删了 /opt/sing-box 后发现某个脚本依赖它：

cd /opt && ln -s server/sing-box sing-box

6.2 plugin-runtime-deps 迁移回滚

如果迁移后 openclaw 启动失败：

mv /var/lib/openclaw/junjunclaw/plugin-runtime-deps /opt/agent/junjunclaw/data/

6.3 数据丢失风险

唯一高风险：Phase 3 的数据迁移。务必先备份：

tar czf /opt/server/backup/pre-governance-$(date +%Y%m%d).tar.gz \
  /opt/agent/junjunclaw/data/plugin-runtime-deps \
  /opt/agent/ywzclaw/data/plugin-runtime-deps \
  /opt/comm/matrix/pgdata

7. 待决策事项

1. financial-team 最终归属：从 ywz-agent-ecosystem 分离后，是独立 git repo 还是继续作为子目录？
2. /opt 根是否保留快捷方式：Phase 2 删除软链接后，你是否接受用 /opt/server/sing-box 代替 /opt/sing-box？
3. plugin-runtime-deps 是否外迁：释放 11G 空间但需要改 docker-compose，是否值得？
4. coding_com 的 git remote：当前有未提交修改，它的 remote 是什么？