mirror of
https://github.com/qingchencloud/clawpanel.git
synced 2026-05-06 20:02:49 +08:00
425 lines
10 KiB
Markdown
425 lines
10 KiB
Markdown
# ClawPanel Linux 部署指南
|
||
|
||
本文介绍如何在 Linux 服务器上部署 **ClawPanel Web 版**，通过浏览器远程管理 OpenClaw。
|
||
|
||
适用场景：云服务器、NAS、家庭 HomeLab、无 GUI 的 Linux 主机。
|
||
|
||
> **ClawPanel** 有 Win/Mac 桌面客户端，但 Linux 没有桌面版。Web 版通过 Vite + Node.js 后端运行，功能与桌面版一致。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [架构说明](#架构说明)
|
||
- [前提条件](#前提条件)
|
||
- [方式一：一键部署](#方式一一键部署)
|
||
- [方式二：手动部署](#方式二手动部署)
|
||
- [方式三：Docker 部署](#方式三docker-部署)
|
||
- [访问 ClawPanel](#访问-clawpanel)
|
||
- [进程守护](#进程守护)
|
||
- [Nginx 反向代理](#nginx-反向代理)
|
||
- [防火墙配置](#防火墙配置)
|
||
- [更新升级](#更新升级)
|
||
- [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 架构说明
|
||
|
||
```
|
||
浏览器 ──HTTP──▶ ClawPanel Web (Vite + dev-api 后端, :1420)
|
||
│
|
||
├── /__api/* 读写 ~/.openclaw/ 配置文件
|
||
├── /ws WebSocket 代理 → Gateway
|
||
└── 管理 Gateway 进程 (启动/停止/重启)
|
||
│
|
||
▼
|
||
OpenClaw Gateway (:18789)
|
||
```
|
||
|
||
**ClawPanel Web 版** = Vite 开发服务器 + `dev-api.js` 后端中间件，提供：
|
||
- 配置读写（`openclaw.json`、`mcp.json`）
|
||
- Gateway 服务管理（启动/停止/重启/状态检测）
|
||
- 设备配对、模型测试、日志查看、备份管理
|
||
- WebSocket 代理到 Gateway
|
||
|
||
---
|
||
|
||
## 前提条件
|
||
|
||
| 依赖 | 最低版本 | 说明 |
|
||
|------|----------|------|
|
||
| Node.js | 18+ | 推荐 22 LTS |
|
||
| npm | 随 Node.js | 包管理器 |
|
||
| Git | 任意 | 克隆仓库 |
|
||
| OpenClaw | 最新 | ClawPanel 管理的对象 |
|
||
|
||
---
|
||
|
||
## 方式一：一键部署
|
||
|
||
```bash
|
||
curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash
|
||
```
|
||
|
||
脚本自动完成：
|
||
1. 检测系统、安装 Node.js（如果缺少）
|
||
2. 安装 OpenClaw 汉化版（如果缺少）
|
||
3. 克隆 ClawPanel 仓库、安装依赖
|
||
4. 创建 systemd 服务、开机自启
|
||
5. 启动 ClawPanel Web，输出访问地址
|
||
|
||
部署完成后访问 `http://服务器IP:1420`。
|
||
|
||
---
|
||
|
||
## 方式二：手动部署
|
||
|
||
### 1. 安装 Node.js
|
||
|
||
**Ubuntu / Debian：**
|
||
|
||
```bash
|
||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||
sudo apt-get install -y nodejs
|
||
```
|
||
|
||
**CentOS / RHEL / Fedora：**
|
||
|
||
```bash
|
||
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
|
||
sudo yum install -y nodejs
|
||
```
|
||
|
||
**Alpine：**
|
||
|
||
```bash
|
||
apk add nodejs npm git
|
||
```
|
||
|
||
验证安装：
|
||
|
||
```bash
|
||
node -v # v22.x.x
|
||
npm -v # 10.x.x
|
||
```
|
||
|
||
### 2. 安装 OpenClaw
|
||
|
||
ClawPanel 是 OpenClaw 的管理工具，需要先安装 OpenClaw：
|
||
|
||
```bash
|
||
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
|
||
```
|
||
|
||
初始化配置（首次）：
|
||
|
||
```bash
|
||
openclaw init
|
||
```
|
||
|
||
### 3. 克隆 ClawPanel
|
||
|
||
```bash
|
||
cd /opt
|
||
sudo git clone https://github.com/qingchencloud/clawpanel.git
|
||
sudo chown -R $(whoami) clawpanel
|
||
cd clawpanel
|
||
npm install
|
||
```
|
||
|
||
### 4. 构建并启动 ClawPanel Web
|
||
|
||
```bash
|
||
npm run build # 构建生产版前端
|
||
npm run serve # 启动 Web 服务器 (默认 0.0.0.0:1420)
|
||
```
|
||
|
||
自定义端口：
|
||
|
||
```bash
|
||
npm run serve -- --port 8080
|
||
```
|
||
|
||
看到以下输出即为成功：
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ 🦀 ClawPanel Web Server (Headless) │
|
||
│ http://localhost:1420/ │
|
||
└─────────────────────────────────────────┘
|
||
[api] API 已启动，配置目录: /root/.openclaw
|
||
```
|
||
|
||
打开浏览器访问 `http://服务器IP:1420` 即可使用 ClawPanel。
|
||
|
||
---
|
||
|
||
## 方式三：Docker 部署
|
||
|
||
> 📖 Docker 完整教程（Compose、自定义镜像、数据持久化等）见 [Docker 部署指南](docker-deploy.md)
|
||
|
||
快速启动：
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name clawpanel \
|
||
--restart unless-stopped \
|
||
-p 1420:1420 \
|
||
-v clawpanel-data:/root/.openclaw \
|
||
node:22-slim \
|
||
sh -c "apt-get update && apt-get install -y git && \
|
||
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && \
|
||
git clone https://github.com/qingchencloud/clawpanel.git /app && \
|
||
cd /app && npm install && npm run build && npm run serve"
|
||
```
|
||
|
||
---
|
||
|
||
## 访问 ClawPanel
|
||
|
||
部署完成后，用浏览器打开：
|
||
|
||
```
|
||
http://服务器IP:1420
|
||
```
|
||
|
||
ClawPanel 会自动检测本机的 OpenClaw 安装，你可以：
|
||
- 管理模型配置（添加/删除/测试 Provider）
|
||
- 启动/停止/重启 Gateway
|
||
- 查看 Gateway 日志
|
||
- 管理 Agent 记忆文件
|
||
- 配置备份与恢复
|
||
|
||
---
|
||
|
||
## 进程守护
|
||
|
||
前台运行会在终端关闭后退出，推荐用 systemd 或 PM2 保持常驻。
|
||
|
||
### 方式一：systemd（推荐）
|
||
|
||
创建服务文件：
|
||
|
||
```bash
|
||
# 先确认 node 的实际路径（不同安装方式路径不同）
|
||
which node
|
||
# 常见路径：/usr/bin/node、/usr/local/bin/node、~/.nvm/versions/node/vXX/bin/node
|
||
|
||
sudo tee /etc/systemd/system/clawpanel.service << EOF
|
||
[Unit]
|
||
Description=ClawPanel Web - OpenClaw Management Panel
|
||
After=network.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=root
|
||
WorkingDirectory=/opt/clawpanel
|
||
ExecStart=$(which node) scripts/serve.js
|
||
Restart=on-failure
|
||
RestartSec=5
|
||
Environment=NODE_ENV=production
|
||
Environment=PATH=/usr/local/bin:/usr/bin:/bin:$(dirname $(which node)):$(dirname $(which openclaw 2>/dev/null || echo /usr/local/bin/openclaw))
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
EOF
|
||
```
|
||
|
||
> ⚠️ **注意**：`ExecStart` 必须使用 Node.js 的**绝对路径**。systemd 不继承用户的 PATH 环境变量，所以 `node` 这种相对路径会找不到。上面的 `$(which node)` 会在创建服务时自动替换为实际路径。`Environment=PATH=...` 确保 OpenClaw CLI 也能被找到。
|
||
|
||
启用并启动：
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable clawpanel
|
||
sudo systemctl start clawpanel
|
||
```
|
||
|
||
常用命令：
|
||
|
||
```bash
|
||
sudo systemctl status clawpanel # 查看状态
|
||
sudo systemctl restart clawpanel # 重启
|
||
sudo journalctl -u clawpanel -f # 查看日志
|
||
```
|
||
|
||
### 方式二：PM2
|
||
|
||
```bash
|
||
npm install -g pm2
|
||
|
||
cd /opt/clawpanel
|
||
npm run build
|
||
pm2 start "npm run serve" --name clawpanel
|
||
pm2 save
|
||
pm2 startup # 开机自启
|
||
```
|
||
|
||
---
|
||
|
||
## Nginx 反向代理
|
||
|
||
如果希望用域名 + HTTPS 访问 ClawPanel：
|
||
|
||
```nginx
|
||
server {
|
||
listen 80;
|
||
server_name panel.yourdomain.com;
|
||
|
||
location / {
|
||
proxy_pass http://127.0.0.1:1420;
|
||
proxy_http_version 1.1;
|
||
proxy_set_header Upgrade $http_upgrade;
|
||
proxy_set_header Connection "upgrade";
|
||
proxy_set_header Host $host;
|
||
proxy_set_header X-Real-IP $remote_addr;
|
||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||
proxy_set_header X-Forwarded-Proto $scheme;
|
||
}
|
||
}
|
||
```
|
||
|
||
> **重要：** 必须配置 WebSocket 升级（`Upgrade` + `Connection`），否则 ClawPanel 无法连接 Gateway。
|
||
|
||
配合 Let's Encrypt 启用 HTTPS：
|
||
|
||
```bash
|
||
sudo apt install certbot python3-certbot-nginx
|
||
sudo certbot --nginx -d panel.yourdomain.com
|
||
```
|
||
|
||
---
|
||
|
||
## 防火墙配置
|
||
|
||
### UFW (Ubuntu/Debian)
|
||
|
||
```bash
|
||
sudo ufw allow 1420/tcp # ClawPanel Web
|
||
sudo ufw allow 18789/tcp # OpenClaw Gateway（如需外部直连）
|
||
```
|
||
|
||
### firewalld (CentOS/RHEL)
|
||
|
||
```bash
|
||
sudo firewall-cmd --permanent --add-port=1420/tcp
|
||
sudo firewall-cmd --reload
|
||
```
|
||
|
||
---
|
||
|
||
## 更新升级
|
||
|
||
### 更新 ClawPanel
|
||
|
||
```bash
|
||
cd /opt/clawpanel # root 部署路径
|
||
# 或 ~/.local/share/clawpanel # 普通用户路径
|
||
|
||
git pull origin main
|
||
npm install --registry https://registry.npmmirror.com
|
||
sudo systemctl restart clawpanel # 或 pm2 restart clawpanel
|
||
```
|
||
|
||
> 国内拉不到 GitHub？用 Gitee 镜像：
|
||
> ```bash
|
||
> git remote set-url origin https://gitee.com/QtCodeCreators/clawpanel.git
|
||
> git pull origin main
|
||
> ```
|
||
|
||
### 更新 OpenClaw
|
||
|
||
**方式一：在 ClawPanel 面板中操作**（推荐）
|
||
|
||
打开「关于」页面 → 点击「检查更新」→ 按提示升级。面板会自动处理 sudo 权限和镜像源。
|
||
|
||
**方式二：命令行手动升级**
|
||
|
||
```bash
|
||
# 非 root 用户需要 sudo
|
||
sudo npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com
|
||
|
||
# 淘宝源安装失败？换官方源重试（可能需要翻墙或代理）
|
||
sudo npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmjs.org
|
||
```
|
||
|
||
> **权限说明**：Linux 全局 npm 包安装需要 root 权限。ClawPanel v0.8.1+ 已自动检测非 root 用户并加 sudo。如仍遇权限问题，手动加 `sudo` 即可。
|
||
|
||
### 更新频率
|
||
|
||
- **ClawPanel**：`git pull` 获取最新代码，无需重新安装依赖（除非 package.json 变了）
|
||
- **OpenClaw**：通过 npm 全局升级，面板会自动检测新版本并提示
|
||
- **前端热更新**：面板支持前端热更新（不需要 git pull），在「关于」页面点击「热更新」按钮即可
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 端口 1420 被占用？
|
||
|
||
```bash
|
||
# 查看占用
|
||
lsof -i :1420
|
||
|
||
# 使用其他端口
|
||
npm run serve -- --port 3000
|
||
```
|
||
|
||
systemd 服务也需要改 ExecStart 中的端口。
|
||
|
||
### Q: 打开面板显示 "openclaw.json 不存在"？
|
||
|
||
需要先安装 OpenClaw 并初始化：
|
||
|
||
```bash
|
||
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
|
||
openclaw init
|
||
```
|
||
|
||
### Q: Gateway 启动/停止按钮不工作？
|
||
|
||
ClawPanel Web 版在 Linux 上通过 `child_process` 管理进程。确保：
|
||
- `openclaw` 命令在 PATH 中
|
||
- 运行 ClawPanel 的用户有权限操作进程
|
||
|
||
```bash
|
||
which openclaw # 应输出路径
|
||
openclaw --version
|
||
```
|
||
|
||
### Q: 从外网无法访问？
|
||
|
||
1. 检查防火墙是否放行端口 1420
|
||
2. 云服务器需在安全组/防火墙规则中开放端口
|
||
3. 推荐使用 Nginx 反向代理 + HTTPS，避免直接暴露端口
|
||
|
||
### Q: 如何同时启动 Gateway 和 ClawPanel？
|
||
|
||
Gateway 和 ClawPanel 是独立进程，需要分别启动：
|
||
|
||
```bash
|
||
# 启动 Gateway（后台）
|
||
openclaw gateway start &
|
||
|
||
# 启动 ClawPanel Web
|
||
cd /opt/clawpanel
|
||
npm run serve
|
||
```
|
||
|
||
或者用 systemd 分别创建两个服务。也可以在 ClawPanel 面板中直接点击「启动」按钮管理 Gateway。
|
||
|
||
### Q: 与桌面版有什么区别？
|
||
|
||
| 功能 | 桌面版 (Win/Mac) | Web 版 (Linux) |
|
||
|------|-----------------|----------------|
|
||
| 配置管理 | ✅ | ✅ |
|
||
| Gateway 管理 | ✅ | ✅ |
|
||
| 模型测试 | ✅ | ✅ |
|
||
| 日志查看 | ✅ | ✅ |
|
||
| 备份管理 | ✅ | ✅ |
|
||
| Agent 记忆 | ✅ | ✅ |
|
||
| ZIP 导出 | ✅ | ❌ |
|
||
| 系统托盘 | ✅ | ❌ |
|
||
| 自动更新 | ✅ | 手动 git pull |
|