sanguo_moziplus_v3/DEPLOYMENT.md

sanguo_moziplus_v3 v0.4 部署指南

快速开始

1. 一键启动

# 启动三实例 tmux 环境
~/.claude/messages/sanguo/start-sanguo-env.sh

# 在各 pane 中分别执行:
# pane 0: cd ~/.claude/projects/sanguo-main && claude
# pane 1: cd ~/.claude/projects/sanguo-backend && claude
# pane 2: cd ~/.claude/projects/sanguo-frontend && claude

2. Web 访问 (可选)

# 启动 Web 终端 (在另一个终端) - 带认证+可写
ttyd -c sanguo:sanguo2024 -W -p 8088 tmux attach -t sanguo_dev

# 访问: http://YOUR_LAN_IP:8088
# 用户名: sanguo
# 密码: sanguo2024

详细步骤

步骤 1: 验证环境

~/.claude/messages/sanguo/test-sanguo-env.sh

预期输出:

=== sanguo 环境测试 ===
✅ 18/18 测试通过

步骤 2: 启动 tmux 会话

~/.claude/messages/sanguo/start-sanguo-env.sh

这将创建:

• pane 0: architect (架构师)
• pane 1: backend (后端开发)
• pane 2: frontend (前端开发)

步骤 3: 启动 Claude Code 实例

在 pane 0 (architect):

cd ~/.claude/projects/sanguo-main
claude

在 pane 1 (backend):

cd ~/.claude/projects/sanguo-backend
claude

在 pane 2 (frontend):

cd ~/.claude/projects/sanguo-frontend
claude

步骤 4: 验证角色加载

在每个实例中，确认 CLAUDE.md 角色定义已加载:

# 在 Claude Code 中输入
角色定义

应该看到对应角色的描述。

步骤 5: 测试 SendMessage

在 architect (pane 0):

SendMessage({
  to: "backend",
  summary: "测试消息",
  message: "这是一条测试消息，请确认收到。"
})

在 backend (pane 1): 应该收到通知并显示消息内容。

在 backend (pane 1) 回复:

SendMessage({
  to: "main",
  summary: "收到测试",
  message: "已收到测试消息，backend 实例正常运行。"
})

tmux 操作指南

快捷键

快捷键	功能
Ctrl+B 0	切换到 pane 0 (architect)
Ctrl+B 1	切换到 pane 1 (backend)
Ctrl+B 2	切换到 pane 2 (frontend)
Ctrl+B o	在 pane 间循环切换
Ctrl+B 方向键	切换到指定方向 pane
Ctrl+B d	分离会话 (detach)
Ctrl+B $	重命名当前窗口

会话管理

# 查看所有会话
tmux ls

# 附加到会话
tmux attach-session -t sanguo_dev

# 杀死会话
tmux kill-session -t sanguo_dev

Web 访问配置

启动 ttyd (带认证+可写)

# 启动 Web 终端 - 带基本认证 + 可写模式
ttyd -c sanguo:sanguo2024 -W -p 8088 tmux attach -t sanguo_dev

# 后台运行
nohup ttyd -c sanguo:sanguo2024 -W -p 8088 tmux attach -t sanguo_dev > /tmp/ttyd.log 2>&1 &

认证信息:

• 用户名: sanguo
• 密码: sanguo2024

注意: -W 参数启用可写模式，允许在 Web 界面中输入命令。

修改认证密码

# 停止当前 ttyd
pkill ttyd

# 用新密码启动 (格式: 用户名:密码)
ttyd -c username:newpassword -W -p 8088 tmux attach -t sanguo_dev

查看本机 IP

# macOS
ifconfig | grep "inet " | grep -v 127.0.0.1

# Linux
ip addr show | grep "inet " | grep -v 127.0.0.1

访问地址

http://YOUR_LAN_IP:8088

浏览器打开后会弹出 HTTP Basic Authentication 对话框，输入用户名和密码即可访问。

停止 ttyd

# 查找进程
ps aux | grep ttyd

# 杀死进程
kill <PID>

故障排查

问题 1: tmux 会话已存在

# 附加到现有会话
tmux attach-session -t sanguo_dev

# 或删除后重建
tmux kill-session -t sanguo_dev
~/.claude/messages/sanguo/start-sanguo-env.sh

问题 2: SendMessage 不工作

检查:

1. 确认各实例都在运行
2. 确认实例名称正确 (main, backend, frontend)
3. 查看 Claude Code 版本 (需要 v2.1.166+)

备选方案: 使用文件消息队列

# 发送消息
~/.claude/messages/sanguo/message.sh send backend "任务内容"

# 读取消息
~/.claude/messages/sanguo/message.sh read

问题 3: 角色定义未生效

检查:

# 确认 CLAUDE.md 存在
ls -la ~/.claude/projects/sanguo-*/.claude/CLAUDE.md

# 查看内容
cat ~/.claude/projects/sanguo-main/.claude/CLAUDE.md

解决: 重新启动 Claude Code

问题 4: 端口被占用

# 查找占用进程
lsof -i :8088

# 更换端口
ttyd -p 8089 tmux attach -t sanguo_dev

高级配置

自定义 tmux 布局

编辑 ~/.tmux-sanguo.conf:

# 调整 pane 大小
split-window -h -p 60  # 水平分割，右侧占 60%

# 调整颜色
set - pane-active-border-style "fg=brightgreen"

# 添加状态栏信息
set - status-right "%H:%M | %Y-%m-%d"

添加更多实例

编辑启动脚本，添加更多 pane:

# 在 pane 2 之后添加
tmux selectp -t 2
tmux split-window -v -p 50
tmux selectp -t 3
tmux split-window -h -p 50

环境变量配置

添加到 ~/.zshrc 或 ~/.bashrc:

# sanguo 环境变量
export SANGUO_SESSION="sanguo_dev"
export SANGUO_WEB_PORT="8088"
export SANGUO_PROJECTS_BASE="$HOME/.claude/projects"

# 快捷命令
alias sanguo-start="$HOME/.claude/messages/sanguo/start-sanguo-env.sh"
alias sanguo-test="$HOME/.claude/messages/sanguo/test-sanguo-env.sh"
alias sanguo-msg="$HOME/.claude/messages/sanguo/message.sh"

生产部署

使用 systemd (Linux)

创建 /etc/systemd/system/sanguo.service:

[Unit]
Description=sanguo Three-Instance Development Environment
After=network.target

[Service]
Type=forking
User=your-user
ExecStart=/usr/bin/tmux new-session -d -s sanguo_dev
ExecStartPost=/bin/sleep 2
ExecStartPost=/usr/bin/ttyd -c sanguo:sanguo2024 -W -p 8088 tmux attach -t sanguo_dev
Restart=on-failure

[Install]
WantedBy=multi-user.target

使用 launchd (macOS)

创建 ~/Library/LaunchAgents/com.sanguo.dev.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.sanguo.dev</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/tmux</string>
        <string>new-session</string>
        <string>-d</string>
        <string>-s</string>
        <string>sanguo_dev</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

加载服务:

launchctl load ~/Library/LaunchAgents/com.sanguo.dev.plist

安全注意事项

Web 访问安全

1. 不要暴露到公网 - 仅在内网使用
2. 使用防火墙 - 限制访问来源
3. 启用认证 - 当前已配置基本认证 (sanguo:sanguo2024)

# 当前配置
ttyd -c sanguo:sanguo2024 -p 8088 tmux attach -t sanguo_dev

# 修改密码
pkill ttyd
ttyd -c your_username:your_password -p 8088 tmux attach -t sanguo_dev

安全等级

配置	安全级别	说明
仅局域网 + 认证	🟡 中	当前配置
添加 HTTPS	🟢 中高	推荐配置
VPN + 内网访问	🟢 高	最安全
直接暴露公网	🔴 危险	绝对避免

数据安全

1. 定期备份项目目录
2. 不要在 CLAUDE.md 中存储敏感信息
3. 使用环境变量管理 API Keys

相关文档

• 完整设计文档
• 快速参考
• 示例工作流