# clawrouter

**Repository Path**: teachitback/clawrouter

## Basic Information

- **Project Name**: clawrouter
- **Description**: clawrouter the bridge for remote clawdroid and clawserver
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-03
- **Last Updated**: 2026-02-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 ClawRouter - TeachItBack 通信基础设施

## 📋 概述

ClawRouter 是 TeachItBack 系统的通信基础设施，为多个 clawserver + ClawDroid 用户组合提供：
- **证书准入控制** - TLS client certs 验证用户身份
- **Topic 隔离** - 基于证书 CN 的用户消息隔离
- **STUN 打洞辅助** - 帮助双方无公网 IP 时建立直连
- **二维码配置** - 简化首次连接配置流程

## 🏗 系统架构

```
ClawRouter Server (teachitback.com)
├── zenohd (tcp/udp:7447)      - Zenoh 路由核心
├── STUN (udp:3478)            - NAT 打洞辅助 (coturn)
└── Cert Manager (tcp:8443)    - 证书颁发与二维码配置 API
```

## ✅ 系统状态

| 组件 | 状态 | 说明 |
|------|------|------|
| Zenoh Router | ✅ 运行中 | 支持 mTLS 证书验证 |
| STUN Server | ✅ 就绪 | 基于 coturn，支持 NAT 穿透 |
| Cert Manager | ✅ 开发完成 | 用户注册和证书管理 |

## 🚀 快速开始

```bash
# 进入 ClawRouter 目录
cd /d/git/teachitback/tibrouter

# 一键启动（自动检测并初始化证书）
python manage.py all
```

### 可用命令

```bash
python manage.py all       # 启动所有服务（自动初始化证书）
python manage.py certman   # 仅启动证书管理器
python manage.py zenoh     # 仅启动 Zenoh 路由器
python manage.py stun      # 仅启动 STUN 服务器
python manage.py stop      # 停止所有服务
python manage.py test      # 运行测试
python manage.py init-ca   # 手动初始化证书
```

### 3. 运行测试

```bash
# 自动启动服务器并运行测试（测试完成后自动停止）
python manage.py test

# 或在服务器运行时单独测试
python manage.py certman  # 保持运行
# 另一个终端:
python manage.py test
```

## 🔐 用户注册与证书流程

### 1. 用户注册

访问证书管理页面：
```bash
# 打开浏览器访问
http://localhost:8443
```

或使用 API 注册：
```bash
# 获取 CAPTCHA
curl http://localhost:8443/captcha

# 用户注册
curl -X POST http://localhost:8443/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "captcha_id": "...",
    "captcha_answer": "..."
  }'
```

### 2. 证书配置

注册成功后：
1. 系统会发送证书配置邮件到指定邮箱
2. 点击邮件中的链接进入证书配置页面
3. 页面显示二维码和证书下载按钮
4. ClawDroid 扫描二维码自动配置
5. clawserver 下载证书并放置到配置目录

## 📡 通信架构

### Topic 命名规范

| 用途 | Topic 格式 | 说明 |
|------|------------|------|
| 命令 | `/ui2a/{username}` | ClawDroid → clawserver |
| 响应 | `/a2ui/{username}` | clawserver → ClawDroid |
| 流式 | `/ui2a/{username}/stream` | 大文件传输 |

### 证书验证流程

1. **连接验证**: clawserver/ClawDroid 连接时出示 client cert
2. **证书验证**: zenohd 验证证书由 CA 签名
3. **CN 提取**: 提取证书 CN 字段作为 user_id
4. **Topic 控制**: 应用层验证 topic 匹配 CN 字段

## 🔧 故障排除

### 常见问题

**1. 服务启动失败**
```bash
# 初始化证书
python manage.py init-ca

# 查看详细日志（Docker 模式）
docker-compose logs

# 检查证书文件
ls -la ca/ certs/
```

**2. 证书验证失败**
```bash
# 验证证书链
openssl verify -CAfile ca/ca.crt certs/server.crt
```

**3. 网络连接问题**
```bash
# 检查端口监听
netstat -an | findstr -E ':(7447|3478|8443)'
```

### 调试技巧

**查看服务状态：**
```bash
# 检查所有服务状态
python manage.py test

# 查看 Docker 日志
docker-compose logs -f cert-manager
```

## 📁 核心文件说明

| 文件 | 说明 |
|------|------|
| `manage.py` | 统一管理脚本（启动/停止/测试/证书管理） |
| `zenohd-config.json5` | Zenoh 路由器配置 |
| `docker-compose.yml` | Docker 服务编排 |
| `init_ca.py` | CA 证书生成脚本 |
| `tests/` | 测试脚本目录 |
| `cert-manager/` | 证书管理器应用 |

## 🎯 下一步计划

- [x] **证书续期机制**: 到期前自动提醒 + 续期流程 ✓
- [ ] **用户管理后台**: 查看在线用户、流量统计
- [ ] **多区域部署**: 就近接入，降低延迟
- [ ] **性能优化**: 大规模用户并发支持

## 📞 技术支持

如果遇到问题：
1. 查看详细日志：`docker-compose logs`
2. 检查服务状态：`docker-compose ps`
3. 验证网络连接：`ping your-server-ip`
4. 查看系统资源：`docker stats`

**当前状态：系统架构完整，支持多用户证书认证！** 🎉