docs: 完成 v0.4 所有文档
新增: - 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>
This commit is contained in:
+343
@@ -0,0 +1,343 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user