mirror of
https://github.com/qingchencloud/clawpanel.git
synced 2026-05-06 20:02:49 +08:00
383 lines
9.5 KiB
Markdown
383 lines
9.5 KiB
Markdown
# ClawPanel Docker 部署指南
|
||
|
||
本文介绍如何用 Docker 部署 **ClawPanel Web 版**，通过浏览器远程管理 OpenClaw。
|
||
|
||
> **ClawPanel** 有 Win/Mac 桌面客户端，但 Linux 没有桌面版。Docker 部署让你在任何有 Docker 的机器上一键跑起 ClawPanel Web 管理面板。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
- [架构说明](#架构说明)
|
||
- [方式一：快速启动](#方式一快速启动)
|
||
- [方式二：Docker Compose（推荐）](#方式二docker-compose推荐)
|
||
- [方式三：自定义 Dockerfile](#方式三自定义-dockerfile)
|
||
- [配置与数据](#配置与数据)
|
||
- [连接 Gateway](#连接-gateway)
|
||
- [Nginx 反向代理](#nginx-反向代理)
|
||
- [常用命令](#常用命令)
|
||
- [更新升级](#更新升级)
|
||
- [常见问题](#常见问题)
|
||
|
||
---
|
||
|
||
## 架构说明
|
||
|
||
```
|
||
浏览器 ──HTTP──▶ ClawPanel Web 容器 (:1420)
|
||
│
|
||
├── /__api/* 读写 ~/.openclaw/ 配置
|
||
├── /ws WebSocket 代理 → Gateway
|
||
└── 管理 Gateway 进程
|
||
│
|
||
▼
|
||
OpenClaw Gateway (容器内或宿主机, :18789)
|
||
```
|
||
|
||
ClawPanel Web 版 = Vite 开发服务器 + `dev-api.js` 后端中间件，在容器内提供完整管理功能。
|
||
|
||
---
|
||
|
||
## 方式一：快速启动
|
||
|
||
最简单的方式，一条命令搞定：
|
||
|
||
```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 && \
|
||
openclaw init 2>/dev/null || true && \
|
||
git clone https://github.com/qingchencloud/clawpanel.git /app && \
|
||
cd /app && npm install && npm run build && \
|
||
npm run serve"
|
||
```
|
||
|
||
访问 `http://服务器IP:1420` 即可使用。
|
||
|
||
> ⚠️ 这种方式每次重建容器都要重新 clone + npm install，适合快速体验。生产环境推荐使用 Compose 或自定义镜像。
|
||
|
||
---
|
||
|
||
## 方式二：Docker Compose（推荐）
|
||
|
||
创建 `docker-compose.yml`：
|
||
|
||
```yaml
|
||
version: '3.8'
|
||
|
||
services:
|
||
clawpanel:
|
||
build:
|
||
context: .
|
||
dockerfile: Dockerfile.clawpanel
|
||
container_name: clawpanel
|
||
restart: unless-stopped
|
||
ports:
|
||
- "1420:1420"
|
||
volumes:
|
||
- openclaw-data:/root/.openclaw
|
||
environment:
|
||
- NODE_ENV=production
|
||
|
||
gateway:
|
||
image: node:22-slim
|
||
container_name: openclaw-gateway
|
||
restart: unless-stopped
|
||
ports:
|
||
- "18789:18789"
|
||
volumes:
|
||
- openclaw-data:/root/.openclaw
|
||
command: >
|
||
sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com &&
|
||
openclaw init 2>/dev/null || true &&
|
||
openclaw gateway start --foreground"
|
||
healthcheck:
|
||
test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
|
||
interval: 30s
|
||
timeout: 5s
|
||
retries: 3
|
||
|
||
volumes:
|
||
openclaw-data:
|
||
```
|
||
|
||
同目录下创建 `Dockerfile.clawpanel`：
|
||
|
||
```dockerfile
|
||
FROM node:22-slim
|
||
|
||
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
|
||
|
||
WORKDIR /app
|
||
RUN git clone https://github.com/qingchencloud/clawpanel.git . && \
|
||
npm install
|
||
|
||
EXPOSE 1420
|
||
|
||
RUN npm run build
|
||
|
||
CMD ["npm", "run", "serve"]
|
||
```
|
||
|
||
启动：
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
这样 ClawPanel 和 Gateway 共享同一个 `openclaw-data` 卷，ClawPanel 可以直接管理 Gateway。
|
||
|
||
---
|
||
|
||
## 方式三：自定义 Dockerfile
|
||
|
||
如果只需要 ClawPanel Web（Gateway 在宿主机或其他地方运行）：
|
||
|
||
```dockerfile
|
||
FROM node:22-slim
|
||
|
||
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
|
||
|
||
# 安装 OpenClaw CLI（ClawPanel 需要读写配置）
|
||
RUN npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
|
||
|
||
WORKDIR /app
|
||
RUN git clone https://github.com/qingchencloud/clawpanel.git . && \
|
||
npm install
|
||
|
||
EXPOSE 1420
|
||
|
||
RUN npm run build
|
||
|
||
CMD ["npm", "run", "serve"]
|
||
```
|
||
|
||
构建并运行：
|
||
|
||
```bash
|
||
docker build -t clawpanel .
|
||
docker run -d \
|
||
--name clawpanel \
|
||
--restart unless-stopped \
|
||
-p 1420:1420 \
|
||
-v ~/.openclaw:/root/.openclaw \
|
||
clawpanel
|
||
```
|
||
|
||
---
|
||
|
||
## 配置与数据
|
||
|
||
### 数据目录
|
||
|
||
ClawPanel 的所有数据都存储在 `~/.openclaw/` 目录中：
|
||
|
||
| 文件/目录 | 说明 |
|
||
|-----------|------|
|
||
| `openclaw.json` | 主配置文件（模型、Gateway、Agent 设置） |
|
||
| `mcp.json` | MCP 服务器配置 |
|
||
| `logs/` | Gateway 日志 |
|
||
| `backups/` | 配置备份 |
|
||
| `agents/` | Agent 数据（记忆、工作区） |
|
||
| `devices/` | 设备配对信息 |
|
||
|
||
### 持久化
|
||
|
||
使用 Docker Volume 或 Bind Mount 持久化数据：
|
||
|
||
```bash
|
||
# Docker Volume（推荐）
|
||
-v clawpanel-data:/root/.openclaw
|
||
|
||
# Bind Mount（方便直接查看文件）
|
||
-v ~/.openclaw:/root/.openclaw
|
||
```
|
||
|
||
### 初始配置
|
||
|
||
首次启动如果没有 `openclaw.json`，可以先在容器内初始化：
|
||
|
||
```bash
|
||
docker exec -it clawpanel openclaw init
|
||
```
|
||
|
||
或者将已有配置挂载进去。
|
||
|
||
---
|
||
|
||
## 连接 Gateway
|
||
|
||
### 场景一：Gateway 在同一个 Compose 中
|
||
|
||
使用上面的 Compose 配置，ClawPanel 和 Gateway 共享数据卷，ClawPanel 自动通过本地回环连接 Gateway。
|
||
|
||
### 场景二：Gateway 在宿主机
|
||
|
||
如果 Gateway 运行在宿主机（不在 Docker 中），ClawPanel 容器需要访问宿主机网络：
|
||
|
||
```bash
|
||
docker run -d \
|
||
--name clawpanel \
|
||
--network host \
|
||
-v ~/.openclaw:/root/.openclaw \
|
||
clawpanel
|
||
```
|
||
|
||
使用 `--network host` 后，容器共享宿主机网络，ClawPanel 可以直接连接 `127.0.0.1:18789`。
|
||
|
||
### 场景三：Gateway 在远程服务器
|
||
|
||
修改 `openclaw.json` 中的 Gateway 端口配置，或在 ClawPanel 面板中设置 Gateway 地址。
|
||
|
||
---
|
||
|
||
## Nginx 反向代理
|
||
|
||
如果希望用域名 + HTTPS 访问：
|
||
|
||
```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 升级头，否则 ClawPanel 无法通过 `/ws` 连接 Gateway。
|
||
|
||
---
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 查看状态
|
||
docker ps | grep clawpanel
|
||
|
||
# 查看日志
|
||
docker logs -f clawpanel
|
||
|
||
# 进入容器
|
||
docker exec -it clawpanel bash
|
||
|
||
# 重启
|
||
docker restart clawpanel
|
||
|
||
# 停止并删除
|
||
docker stop clawpanel && docker rm clawpanel
|
||
```
|
||
|
||
---
|
||
|
||
## 更新升级
|
||
|
||
### 更新 ClawPanel
|
||
|
||
```bash
|
||
docker exec -it clawpanel bash -c "cd /app && git pull origin main && npm install"
|
||
docker restart clawpanel
|
||
```
|
||
|
||
### 使用 Compose 重建
|
||
|
||
```bash
|
||
docker compose build --no-cache clawpanel
|
||
docker compose up -d clawpanel
|
||
```
|
||
|
||
### 更新 OpenClaw
|
||
|
||
```bash
|
||
docker exec -it clawpanel npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com
|
||
```
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### Q: 容器启动后打开面板是空白？
|
||
|
||
检查容器日志：
|
||
|
||
```bash
|
||
docker logs clawpanel
|
||
```
|
||
|
||
确认看到 `VITE ready` 和 `[dev-api] 开发 API 已启动` 输出。
|
||
|
||
### Q: 面板里点"安装 OpenClaw"失败 / 拉取不了？
|
||
|
||
面板中的"安装 OpenClaw"走的是 `npm install -g`（在容器内通过网络下载安装），**不是拉取 Docker 镜像**。失败原因通常是容器网络不通或 npm 源访问慢。
|
||
|
||
**推荐方案（二选一）：**
|
||
|
||
1. **使用一体镜像（最简单）**：直接用预装了 OpenClaw + Gateway + ClawPanel 的一体镜像，不需要在面板里点安装：
|
||
```bash
|
||
docker run -d --name openclaw -p 1420:1420 -p 18789:18789 \
|
||
-v openclaw-data:/root/.openclaw \
|
||
ghcr.io/qingchencloud/openclaw:latest
|
||
```
|
||
> 一体镜像仓库：[github.com/qingchencloud/openclaw-docker](https://github.com/qingchencloud/openclaw-docker)
|
||
|
||
2. **在 Dockerfile 中预装**：构建镜像时就安装好 OpenClaw，避免运行时下载：
|
||
```dockerfile
|
||
FROM node:22-slim
|
||
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
|
||
# 预装 OpenClaw CLI（使用国内镜像源加速）
|
||
RUN npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
|
||
# ... 后续 ClawPanel 安装步骤
|
||
```
|
||
|
||
**临时方案**：如果容器已经在运行，可以手动进入容器安装：
|
||
```bash
|
||
docker exec -it clawpanel npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
|
||
```
|
||
|
||
### Q: 面板显示 "openclaw.json 不存在"？
|
||
|
||
在容器内初始化 OpenClaw：
|
||
|
||
```bash
|
||
docker exec -it clawpanel openclaw init
|
||
```
|
||
|
||
### Q: Gateway 按钮不工作（Docker 环境）？
|
||
|
||
容器内管理 Gateway 进程需要特殊权限。推荐方案：
|
||
|
||
1. **Compose 模式**：Gateway 作为独立容器运行，用 `docker compose restart gateway` 管理
|
||
2. **Host 网络模式**：`--network host` 让 ClawPanel 直接管理宿主机进程
|
||
|
||
### Q: 数据会丢失吗？
|
||
|
||
只要正确配置了 Volume 挂载（`-v clawpanel-data:/root/.openclaw`），容器删除重建不会丢失数据。
|
||
|
||
### Q: 与桌面版有什么区别？
|
||
|
||
| 功能 | 桌面版 (Win/Mac) | Docker Web 版 |
|
||
|------|-----------------|---------------|
|
||
| 配置管理 | ✅ | ✅ |
|
||
| Gateway 管理 | ✅ | ⚠️ 需 host 网络或 Compose |
|
||
| 模型测试 | ✅ | ✅ |
|
||
| 日志查看 | ✅ | ✅ |
|
||
| 备份管理 | ✅ | ✅ |
|
||
| Agent 记忆 | ✅ | ✅ |
|
||
| ZIP 导出 | ✅ | ❌ |
|
||
| 系统托盘 | ✅ | ❌ |
|
||
| 自动更新 | ✅ | 手动重建镜像 |
|