# aaa

**Repository Path**: td-robot/aaa

## Basic Information

- **Project Name**: aaa
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-01
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 虾助理边缘网关 (Xiabot Local Server)

运行在无屏幕边缘 AI 硬件上的本地守护进程与 API 服务端。

## 硬件平台
- NanoPi M5 (RK3576, ARM64)
- 6 TOPS NPU
- Ubuntu 操作系统

## 功能模块

### 1. 网络自愈与配置管理
- 开机自动连接 WiFi，失败则降级为 AP 热点模式
- Captive Portal 强制门户，连接 AP 自动弹出配网页面
- WiFi 扫描与配网 API
- 防变砖自愈机制

### 2. 系统灾备与一键还原
- **增量快照**：使用 rsync + 硬链接，节省空间（日常备份）
- **全量备份**：完整复制，独立存储（重要节点备份）
- 快照管理：创建、列表、还原、删除
- 出厂快照：一键恢复出厂设置
- 硬件按键触发还原（Recovery 长按 15 秒）

### 3. OpenClaw AI 引擎管理
- 服务状态查询与控制（启动/停止/重启）
- 动态配置修改
- Skills 插件管理
- 健康监控与统计

### 4. 云端通信与实时监控
- WebSocket 长连接，实时双向通信
- 设备认证与自动登录
- 命令监听与执行
- 系统指标实时上报（每 1.5 秒）
  - CPU 使用率
  - 内存使用率
  - 磁盘使用率
  - CPU 温度
  - 网络延时

### 5. 设备管理
- mDNS 局域网发现
- 设备重命名
- 系统信息查询
- 远程重启/关机

## 快速开始

### 1. 安装依赖
```bash
cd /opt/xia_assistant/xiabot-server
python3 -m venv venv
source venv/bin/activate
pip3 install -r requirements.txt
```

### 2. 配置系统文件

#### 2.1 配置 sudoers (允许无密码执行系统命令)
```bash
sudo visudo
```

添加以下内容:
```
# 虾助理服务权限
pi ALL=(ALL) NOPASSWD: /bin/systemctl start xiabot
pi ALL=(ALL) NOPASSWD: /bin/systemctl stop xiabot
pi ALL=(ALL) NOPASSWD: /bin/systemctl restart xiabot
pi ALL=(ALL) NOPASSWD: /bin/systemctl status xiabot
pi ALL=(ALL) NOPASSWD: /bin/systemctl start captive-portal
pi ALL=(ALL) NOPASSWD: /bin/systemctl stop captive-portal
pi ALL=(ALL) NOPASSWD: /bin/systemctl restart captive-portal
pi ALL=(ALL) NOPASSWD: /usr/sbin/reboot
pi ALL=(ALL) NOPASSWD: /usr/sbin/shutdown
pi ALL=(ALL) NOPASSWD: /usr/bin/nmcli
pi ALL=(ALL) NOPASSWD: /bin/cp /tmp/hostname /etc/hostname
pi ALL=(ALL) NOPASSWD: /usr/bin/rsync * /etc/NetworkManager/system-connections/
```

或使用脚本自动配置:
```bash
sudo ./scripts/setup_sudoers.sh
```

#### 2.2 配置 systemd 服务

创建主服务 `/etc/systemd/system/xiabot.service`:
```ini
[Unit]
Description=Xiabot Local Server
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/opt/xia_assistant/xiabot-server
Environment="PATH=/opt/xia_assistant/xiabot-server/venv/bin:/usr/local/bin:/usr/bin:/bin"
ExecStart=/opt/xia_assistant/xiabot-server/venv/bin/python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

创建网络自愈服务 `/etc/systemd/system/xiabot-network.service`:
```ini
[Unit]
Description=Xiabot Network Auto-Heal
After=network.target NetworkManager.service
Wants=NetworkManager.service

[Service]
Type=oneshot
ExecStart=/opt/xia_assistant/xiabot-server/scripts/autohotspot.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target
```

创建 Captive Portal 服务 `/etc/systemd/system/captive-portal.service`:
```ini
[Unit]
Description=Captive Portal DNS Service
After=network.target

[Service]
Type=forking
ExecStart=/usr/sbin/dnsmasq --conf-file=/etc/dnsmasq.d/captive-portal.conf
ExecReload=/bin/kill -HUP $MAINPID
PIDFile=/var/run/dnsmasq-captive.pid
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

#### 2.3 配置 dnsmasq (Captive Portal)

创建 `/etc/dnsmasq.d/captive-portal.conf`:
```conf
# 监听 AP 热点接口
interface=wlan0
bind-interfaces

# DHCP 配置
dhcp-range=10.42.0.10,10.42.0.250,12h
dhcp-option=3,10.42.0.1
dhcp-option=6,10.42.0.1

# DNS 劫持 - 将所有域名解析到本机
address=/#/10.42.0.1

# PID 文件
pid-file=/var/run/dnsmasq-captive.pid
```

或使用脚本自动配置:
```bash
sudo ./scripts/setup_captive_portal.sh
```

#### 2.4 启用服务
```bash
sudo systemctl daemon-reload
sudo systemctl enable xiabot.service
sudo systemctl enable xiabot-network.service
sudo systemctl start xiabot.service
sudo systemctl start xiabot-network.service
```

### 3. 手动启动 (开发模式)
```bash
cd /opt/xia_assistant/xiabot-server
source venv/bin/activate
python3 -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```

## API 文档

启动服务后访问交互式文档: http://localhost:8000/docs

### 1. 网络管理 API

#### 扫描 WiFi
```http
GET /api/v1/network/wifi/scan
```

#### 连接 WiFi
```http
POST /api/v1/network/wifi/connect
Content-Type: application/json

{
  "ssid": "WiFi名称",
  "password": "WiFi密码"
}
```

#### 启动/停止 AP 热点
```http
POST /api/v1/network/ap/start
POST /api/v1/network/ap/stop
```

#### 获取网络状态
```http
GET /api/v1/network/status
```

### 2. 系统监控 API

#### 获取系统指标
```http
GET /api/v1/system/metrics
```

返回示例：
```json
{
  "cpu_percent": 25.0,
  "memory_percent": 70.9,
  "memory_used_mb": 2767.21,
  "memory_total_mb": 3904.67,
  "disk_percent": 13.2,
  "disk_used_gb": 6.76,
  "disk_total_gb": 53.98,
  "disk_free_gb": 44.47,
  "temperature": 42.5
}
```

### 3. 快照备份与还原 API

#### 创建增量快照
```http
POST /api/v1/system/snapshot
Content-Type: application/json

{
  "description": "手动备份"
}
```

#### 创建全量备份
```http
POST /api/v1/system/full-backup
Content-Type: application/json

{
  "description": "系统升级前备份"
}
```

#### 列出所有快照
```http
GET /api/v1/system/snapshots
```

#### 还原快照
```http
POST /api/v1/system/restore
Content-Type: application/json

{
  "snapshot_name": "snapshot_20260326_123456"
}
```

#### 删除快照
```http
DELETE /api/v1/system/snapshot/{snapshot_name}
```

#### 创建出厂快照
```http
POST /api/v1/system/factory/create
```

#### 恢复出厂设置
```http
POST /api/v1/system/factory/restore
```

⚠️ **危险操作**：会清空所有用户数据并恢复到出厂状态

### 4. OpenClaw 管理 API

#### 获取服务状态
```http
GET /api/v1/openclaw/status
```

#### 控制服务
```http
POST /api/v1/openclaw/control
Content-Type: application/json

{
  "action": "start"  // start, stop, restart
}
```

#### 获取配置
```http
GET /api/v1/openclaw/config
```

#### 更新配置
```http
PUT /api/v1/openclaw/config
Content-Type: application/json

{
  "config": {
    "key": "value"
  }
}
```

#### 获取 Skills 列表
```http
GET /api/v1/openclaw/skills
```

#### 监控健康检查
```http
GET /api/v1/openclaw/monitor/health
GET /api/v1/openclaw/monitor/stats
GET /api/v1/openclaw/monitor/history
```

### 5. 云端通信 API

#### 获取云端认证状态
```http
GET /api/v1/system/cloud/status
```

#### 手动登录云端
```http
POST /api/v1/system/cloud/login
```

#### 发送消息到云端
```http
POST /api/v1/cloud/send
Content-Type: application/json

{
  "action": "custom_action",
  "payload": {
    "data": "value"
  }
}
```

### 6. 设备管理 API

#### 获取设备信息
```http
GET /api/v1/system/info
```

#### 重命名设备
```http
POST /api/v1/system/rename
Content-Type: application/json

{
  "hostname": "新设备名"
}
```

#### 获取 mDNS 信息
```http
GET /api/v1/system/mdns-info
```

#### 系统重启/关机
```http
POST /api/v1/system/reboot
POST /api/v1/system/shutdown
```

## 项目结构
```
xiabot-server/
├── app/
│   ├── main.py                          # FastAPI 入口
│   ├── core/
│   │   └── config.py                    # 配置管理
│   ├── api/v1/
│   │   ├── network.py                   # 网络管理 API
│   │   ├── system.py                    # 系统管理 API
│   │   ├── openclaw.py                  # OpenClaw 管理 API
│   │   ├── openclaw_devices.py          # OpenClaw 设备管理
│   │   └── cloud.py                     # 云端通信 API
│   ├── services/
│   │   ├── nmcli_service.py             # NetworkManager 服务
│   │   ├── snapshot_backup.py           # 快照备份服务
│   │   ├── openclaw_service.py          # OpenClaw 服务
│   │   ├── openclaw_monitor.py          # OpenClaw 监控
│   │   ├── openclaw_extended_service.py # OpenClaw 扩展服务
│   │   ├── cloud_auth_service.py        # 云端认证服务
│   │   ├── cloud_command_listener.py    # 云端命令监听
│   │   ├── cloud_command_handler.py     # 云端命令处理
│   │   ├── metrics_reporter.py          # 指标上报服务
│   │   ├── recovery_button_service.py   # 恢复按键服务
│   │   └── update.py                    # OTA 更新服务
│   └── schemas/
│       ├── network_schema.py            # 网络数据模型
│       ├── system_schema.py             # 系统数据模型
│       └── openclaw_schema.py           # OpenClaw 数据模型
├── scripts/
│   ├── autohotspot.sh                   # 网络自愈脚本
│   ├── setup_captive_portal.sh          # Captive Portal 配置
│   ├── setup_sudoers.sh                 # sudoers 配置
│   ├── start_router.sh                  # 路由器启动脚本
│   └── update_systemd_for_ota.sh        # OTA 更新配置
├── static/
│   └── index.html                       # 配网页面
├── docs/
│   └── CAPTIVE_PORTAL.md                # Captive Portal 文档
├── requirements.txt                     # Python 依赖
└── version.txt                          # 版本信息
```

## 数据存储

### 代码区（只读）
```
/opt/xia_assistant/xiabot-server/
```
- 应用程序代码
- 脚本文件
- 静态资源

### 数据区（可读写）
```
/userdata/pi/xia_data/
├── config/          # 配置文件
├── data/            # 应用数据
├── logs/            # 日志文件
├── snapshots/       # 快照备份
└── backups/         # 外部备份
```

## 服务管理

### 查看服务状态
```bash
sudo systemctl status xiabot
sudo systemctl status xiabot-network
sudo systemctl status captive-portal
```

### 启动/停止/重启服务
```bash
sudo systemctl start xiabot
sudo systemctl stop xiabot
sudo systemctl restart xiabot
```

### 查看日志
```bash
# 实时查看日志
sudo journalctl -u xiabot -f

# 查看最近 100 条日志
sudo journalctl -u xiabot -n 100

# 查看云端通信日志
sudo journalctl -u xiabot -f | grep cloud
```

## 开发状态

### 已完成功能
- [x] 网络自愈脚本（开机自动连接 WiFi/降级 AP）
- [x] Captive Portal 强制门户（自动弹出配网页面）
- [x] WiFi 扫描与配网 API
- [x] 系统快照备份与还原（增量 + 全量）
- [x] 出厂快照与一键恢复
- [x] 系统监控 API（CPU、内存、磁盘、温度）
- [x] 系统监控实时上报（WebSocket，1.5 秒间隔）
- [x] 网络延时监控（ping 测试）
- [x] OpenClaw 服务管理 API
- [x] OpenClaw 健康监控
- [x] 云端认证与自动登录
- [x] WebSocket 云端通信
- [x] 云端命令监听与执行
- [x] mDNS 局域网发现
- [x] 设备重命名
- [x] 远程重启/关机


## 技术栈

- **后端框架**: FastAPI + Uvicorn
- **数据验证**: Pydantic
- **系统监控**: psutil
- **网络管理**: NetworkManager (nmcli)
- **备份工具**: rsync (增量备份 + 硬链接)
- **DNS 服务**: dnsmasq (Captive Portal)
- **服务发现**: Avahi (mDNS)
- **进程管理**: systemd
- **实时通信**: WebSocket

## 版本信息

当前版本: 见 `version.txt`

## 许可证

专有软件 - 虾助理团队