sanguo_moziplus_v3/DEPLOYMENT.md

# sanguo_moziplus_v3 v0.4 部署指南

## 快速开始

### 1. 一键启动

```bash
# 启动三实例 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 访问 (可选)

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

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

## 详细步骤

### 步骤 1: 验证环境

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

预期输出:
```
=== sanguo 环境测试 ===
✅ 18/18 测试通过
```

### 步骤 2: 启动 tmux 会话

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

这将创建:
- pane 0: architect (架构师)
- pane 1: backend (后端开发)
- pane 2: frontend (前端开发)

### 步骤 3: 启动 Claude Code 实例

**在 pane 0 (architect)**:
```bash
cd ~/.claude/projects/sanguo-main
claude
```

**在 pane 1 (backend)**:
```bash
cd ~/.claude/projects/sanguo-backend
claude
```

**在 pane 2 (frontend)**:
```bash
cd ~/.claude/projects/sanguo-frontend
claude
```

### 步骤 4: 验证角色加载

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

```bash
# 在 Claude Code 中输入
角色定义
```

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

### 步骤 5: 测试 SendMessage

**在 architect (pane 0)**:
```javascript
SendMessage({
  to: "backend",
  summary: "测试消息",
  message: "这是一条测试消息，请确认收到。"
})
```

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

**在 backend (pane 1) 回复**:
```javascript
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 $` | 重命名当前窗口 |

### 会话管理

```bash
# 查看所有会话
tmux ls

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

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

## Web 访问配置

### 启动 ttyd (带认证+可写)

```bash
# 启动 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 界面中输入命令。

### 修改认证密码

```bash
# 停止当前 ttyd
pkill ttyd

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

### 查看本机 IP

```bash
# 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

```bash
# 查找进程
ps aux | grep ttyd

# 杀死进程
kill <PID>
```

## 故障排查

### 问题 1: tmux 会话已存在

```bash
# 附加到现有会话
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+)

**备选方案**: 使用文件消息队列
```bash
# 发送消息
~/.claude/messages/sanguo/message.sh send backend "任务内容"

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

### 问题 3: 角色定义未生效

**检查**:
```bash
# 确认 CLAUDE.md 存在
ls -la ~/.claude/projects/sanguo-*/.claude/CLAUDE.md

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

**解决**: 重新启动 Claude Code

### 问题 4: 端口被占用

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

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

## 高级配置

### 自定义 tmux 布局

编辑 `~/.tmux-sanguo.conf`:

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

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

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

### 添加更多实例

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

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

### 环境变量配置

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

```bash
# 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`:

```ini
[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
<?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>
```

加载服务:
```bash
launchctl load ~/Library/LaunchAgents/com.sanguo.dev.plist
```

## 安全注意事项

### Web 访问安全

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

```bash
# 当前配置
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

## 相关文档

- [完整设计文档](./docs/design/04-design-v0.4.md)
- [快速参考](./docs/04-quick-reference.md)
- [示例工作流](./docs/05-example-workflows.md)