claude_dev
ddccd8fbfa
新增: - DEPLOYMENT.md - 完整部署指南 - README.md - 项目说明和快速开始 更新内容: - 部署步骤详解 - tmux 操作指南 - Web 访问配置 - 故障排查指南 - 高级配置选项 - 生产部署方案 (systemd/launchd) - 安全注意事项 v0.4 完整交付: ✅ 设计文档 (04-design-v0.4.md) ✅ 快速参考 (04-quick-reference.md) ✅ 示例工作流 (05-example-workflows.md) ✅ 部署指南 (DEPLOYMENT.md) ✅ 项目说明 (README.md) ✅ 三实例项目结构 ✅ 角色 Skills ✅ 系统脚本 (tmux/启动/消息/测试) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
344 lines
6.3 KiB
Markdown
344 lines
6.3 KiB
Markdown
# 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 -p 8088 tmux attach -t sanguo_dev
|
|
|
|
# 访问: http://YOUR_LAN_IP:8088
|
|
```
|
|
|
|
## 详细步骤
|
|
|
|
### 步骤 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 -p 8088 tmux attach -t sanguo_dev
|
|
|
|
# 后台运行
|
|
nohup ttyd -p 8088 tmux attach -t sanguo_dev > /tmp/ttyd.log 2>&1 &
|
|
```
|
|
|
|
### 查看本机 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
|
|
```
|
|
|
|
### 停止 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 -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. **添加认证** - ttyd 支持基本认证
|
|
|
|
```bash
|
|
# 启用基本认证
|
|
ttyd -c username:password -p 8088 tmux attach -t sanguo_dev
|
|
```
|
|
|
|
### 数据安全
|
|
|
|
1. 定期备份项目目录
|
|
2. 不要在 CLAUDE.md 中存储敏感信息
|
|
3. 使用环境变量管理 API Keys
|
|
|
|
## 相关文档
|
|
|
|
- [完整设计文档](./docs/design/04-design-v0.4.md)
|
|
- [快速参考](./docs/04-quick-reference.md)
|
|
- [示例工作流](./docs/05-example-workflows.md)
|