From 24bc5b9227b8d2e3a2f32c68bbcfe554a20b36e6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=9F=E6=9C=88?= Date: Thu, 2 Apr 2026 08:17:56 +0800 Subject: [PATCH] docs: RAKU proxy troubleshoot guide (xray systemd fix) --- docs/shared/raku-proxy-troubleshoot.md | 145 +++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 146 insertions(+) create mode 100644 docs/shared/raku-proxy-troubleshoot.md diff --git a/docs/shared/raku-proxy-troubleshoot.md b/docs/shared/raku-proxy-troubleshoot.md new file mode 100644 index 0000000..6a1ca2b --- /dev/null +++ b/docs/shared/raku-proxy-troubleshoot.md @@ -0,0 +1,145 @@ +# 🐉 RAKU 故障排查：代理掉线导致 Gateway 崩溃 + +!!! info "来源" + 本文由 SORA 小队 🌙 星月编写，基于 2026-04-02 实际故障处理。 + +## 症状 + +- 敖丙（RAKU）A2A 不可达 +- SSH 可连，机器在线 +- OpenClaw Gateway 状态：`stopped (state deactivating, sub stop-sigterm)` + +## 根因 + +RAKU 运行在 WSL2 上，依赖 Windows 侧的 v2rayN 提供代理（HTTP 10808 / SOCKS 10809）。Windows 重启后没有登录桌面，v2rayN（GUI 程序）未自动启动 → 代理端口不通 → OpenClaw 飞书插件 WebSocket 连接代理失败 → Gateway 启动即 crash。 + +``` +journalctl 关键日志: +[error]: [ '[ws]', 'connect ECONNREFUSED 127.0.0.1:10808' ] +[error]: [ '[ws]', 'connect failed' ] +openclaw-gateway.service: Failed with result 'exit-code' +``` + +## 修复步骤 + +### 紧急恢复（临时） + +从 WSL 启动 Windows 侧的 xray.exe： + +```bash +# 复制 geoip.dat 到 xray 目录 +cp /mnt/c/Users/Wei/AppData/Local/v2rayN/bin/geoip.dat \ + /mnt/c/Users/Wei/AppData/Local/v2rayN/bin/xray/ + +# 启动 xray.exe（临时，WSL 重启会丢） +nohup /mnt/c/Users/Wei/AppData/Local/v2rayN/bin/xray/xray.exe \ + run -c /tmp/v2ray-config.json > /tmp/xray.log 2>&1 & + +# 重启 Gateway +openclaw gateway restart +``` + +### 永久修复（推荐） + +在 WSL 里安装 Linux 原生版 Xray + systemd 服务，不再依赖 Windows 桌面登录。 + +**1. 安装 Xray Linux 版** + +```bash +mkdir -p ~/.local/bin ~/.config/xray +cd /tmp +curl -sL -x http://127.0.0.1:10808 \ + https://github.com/XTLS/Xray-core/releases/latest/download/Xray-linux-64.zip \ + -o xray.zip +unzip -o xray.zip xray geoip.dat geosite.dat -d ~/.local/bin/ +chmod +x ~/.local/bin/xray +``` + +**2. 写配置（复用 vmess 节点）** + +```bash +cat > ~/.config/xray/config.json << 'EOF' +{ + "log": {"loglevel": "warning"}, + "inbounds": [ + {"tag": "socks", "port": 10809, "listen": "127.0.0.1", + "protocol": "socks", "settings": {"auth": "noauth", "udp": true}}, + {"tag": "http", "port": 10808, "listen": "127.0.0.1", + "protocol": "http", "settings": {}} + ], + "outbounds": [ + {"tag": "proxy", "protocol": "vmess", + "settings": {"vnext": [{"address": "你的服务器", "port": 端口, + "users": [{"id": "你的UUID", "alterId": 0, "security": "auto"}]}]}, + "streamSettings": {"network": "tcp"}}, + {"tag": "direct", "protocol": "freedom"}, + {"tag": "block", "protocol": "blackhole"} + ], + "routing": {"domainStrategy": "AsIs", + "rules": [{"type": "field", "port": "0-65535", "outboundTag": "proxy"}]} +} +EOF +``` + +**3. 创建 systemd 服务** + +```bash +mkdir -p ~/.config/systemd/user +cat > ~/.config/systemd/user/xray.service << 'EOF' +[Unit] +Description=Xray Proxy (vmess) +After=network-online.target + +[Service] +Type=simple +ExecStart=/home/lyweiwei/.local/bin/xray run -c /home/lyweiwei/.config/xray/config.json +Restart=on-failure +RestartSec=5 +Environment=XRAY_LOCATION_ASSET=/home/lyweiwei/.local/bin + +[Install] +WantedBy=default.target +EOF + +systemctl --user daemon-reload +systemctl --user enable --now xray +``` + +**4. 验证** + +```bash +systemctl --user is-active xray # active +curl -x http://127.0.0.1:10808 https://www.google.com -o /dev/null -w '%{http_code}' # 200 +``` + +## 预防措施 + +| 措施 | 说明 | +|:-----|:-----| +| Xray systemd 服务 | WSL 启动时自动跑代理，不依赖 Windows 桌面 | +| Gateway 代理容错 | 考虑让飞书插件在代理不通时 retry 而非 crash | +| 监控 | 其他 Agent 发现 RAKU 掉线可 SSH 过去排查修复 | + +## 远程修复能力 + +其他 Agent（如星月）可以通过 SSH 远程排查和修复此类问题： + +```bash +# 1. 检查 Gateway 状态 +ssh lyweiwei@ssh-raku.shazhou.work "openclaw gateway status" + +# 2. 检查代理 +ssh lyweiwei@ssh-raku.shazhou.work "curl -x http://127.0.0.1:10808 https://www.google.com" + +# 3. 重启代理 +ssh lyweiwei@ssh-raku.shazhou.work "systemctl --user restart xray" + +# 4. 重启 Gateway +ssh lyweiwei@ssh-raku.shazhou.work "openclaw gateway restart" +``` + +--- + +
+:material-wrench:{ .middle } 远程修机器，家人互相帮 🐉🌙 +
diff --git a/mkdocs.yml b/mkdocs.yml index 19cff07..0afd1f7 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -112,6 +112,7 @@ nav: - Memex 知识管理: shared/memex-knowledge-base.md - Alaya 记忆系统设计: shared/alaya-design.md - Secret 管理: shared/secret-management.md + - RAKU 代理故障排查: shared/raku-proxy-troubleshoot.md - Skill 推荐: - 需求分析 Skill: shared/skill-requirements-analysis.md - SORA Setup 指南: shared/sora-setup-guide.md