From b709b7083942ccc9988e4a7f161dcbb31502f5a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=99=B4=E5=A4=A9?= Date: Thu, 5 Mar 2026 23:10:46 +0800 Subject: [PATCH] =?UTF-8?q?fix:=20rewrite=20deploy=20docs=20to=20be=20abou?= =?UTF-8?q?t=20ClawPanel=20Web=E7=89=88=20(not=20OpenClaw)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ClawPanel is the management tool - the docs should be about deploying ClawPanel itself on Linux/Docker, not OpenClaw Gateway. - Rewrite linux-deploy.md: ClawPanel Web版 Linux deployment guide - Rewrite docker-deploy.md: ClawPanel Web版 Docker deployment guide - Rewrite linux-deploy.sh: one-click script deploys ClawPanel Web + OpenClaw - Update README deploy sections with correct descriptions and commands - Update index.html deploy section and docs center card descriptions - Port changed from 18789 (Gateway) to 1420 (ClawPanel Web) --- README.md | 19 +- docs/docker-deploy.md | 725 +++++++++++---------------------------- docs/index.html | 28 +- docs/linux-deploy.md | 729 +++++++++++++--------------------------- scripts/linux-deploy.sh | 247 ++++++-------- 5 files changed, 571 insertions(+), 1177 deletions(-) diff --git a/README.md b/README.md index a39521b..3f73289 100644 --- a/README.md +++ b/README.md @@ -75,26 +75,31 @@ ClawPanel 是 [OpenClaw](https://github.com/1186258278/OpenClawChineseTranslatio | DEB | `ClawPanel_x.x.x_amd64.deb` | Debian / Ubuntu：`sudo dpkg -i *.deb` | | RPM | `ClawPanel-x.x.x-1.x86_64.rpm` | Fedora / RHEL：`sudo rpm -i *.rpm` | -### Linux 服务器（无 GUI） +### Linux 服务器（Web 版） -不需要桌面环境，一键命令部署 OpenClaw Gateway，通过端口远程访问： +没有桌面环境？一键部署 ClawPanel Web 版，通过浏览器远程管理 OpenClaw： ```bash curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash ``` -📖 详细教程见 [Linux 服务器部署指南](docs/linux-deploy.md) +部署完成后访问 `http://服务器IP:1420`，功能与桌面版一致。 + +📖 详细教程见 [Linux 部署指南](docs/linux-deploy.md) ### Docker 部署 ```bash -docker run -d --name openclaw --restart unless-stopped \ - -p 18789:18789 -v openclaw-data:/root/.openclaw \ +docker run -d --name clawpanel --restart unless-stopped \ + -p 1420:1420 -v clawpanel-data:/root/.openclaw \ node:22-slim \ - sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && openclaw gateway start" + 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 && npx vite --port 1420 --host 0.0.0.0" ``` -📖 详细教程见 [Docker 部署指南](docs/docker-deploy.md)（含 Compose、Dockerfile、Nginx 反向代理、Ollama 联动等） +📖 详细教程见 [Docker 部署指南](docs/docker-deploy.md)（含 Compose、自定义镜像、Nginx 反向代理等） ## 功能特性 diff --git a/docs/docker-deploy.md b/docs/docker-deploy.md index 8a62db5..a60f7cc 100644 --- a/docs/docker-deploy.md +++ b/docs/docker-deploy.md @@ -1,665 +1,350 @@ -# Docker 部署指南 +# ClawPanel Docker 部署指南 -使用 Docker 一键部署 OpenClaw Gateway，无需安装 Node.js，开箱即用。 +本文介绍如何用 Docker 部署 **ClawPanel Web 版**，通过浏览器远程管理 OpenClaw。 + +> **ClawPanel** 有 Win/Mac 桌面客户端，但 Linux 没有桌面版。Docker 部署让你在任何有 Docker 的机器上一键跑起 ClawPanel Web 管理面板。 + +--- ## 目录 -- [快速开始](#快速开始) -- [Docker Compose 部署](#docker-compose-部署) -- [配置说明](#配置说明) -- [模型配置](#模型配置) -- [数据持久化](#数据持久化) -- [网络与端口](#网络与端口) -- [反向代理](#反向代理) +- [架构说明](#架构说明) +- [方式一：快速启动](#方式一快速启动) +- [方式二：Docker Compose（推荐）](#方式二docker-compose推荐) +- [方式三：自定义 Dockerfile](#方式三自定义-dockerfile) +- [配置与数据](#配置与数据) +- [连接 Gateway](#连接-gateway) +- [Nginx 反向代理](#nginx-反向代理) - [常用命令](#常用命令) -- [升级](#升级) +- [更新升级](#更新升级) - [常见问题](#常见问题) --- -## 快速开始 +## 架构说明 -**一条命令启动：** - -```bash -docker run -d \ - --name openclaw \ - --restart unless-stopped \ - -p 18789:18789 \ - -v openclaw-data:/root/.openclaw \ - node:22-slim \ - sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && openclaw gateway start" +``` +浏览器 ──HTTP──▶ ClawPanel Web 容器 (:1420) + │ + ├── /__api/* 读写 ~/.openclaw/ 配置 + ├── /ws WebSocket 代理 → Gateway + └── 管理 Gateway 进程 + │ + ▼ + OpenClaw Gateway (容器内或宿主机, :18789) ``` -启动后访问 `http://你的服务器IP:18789`。 - -> ⚠️ 首次启动需要下载安装 OpenClaw，可能需要 1-2 分钟。后续重启会直接启动。 +ClawPanel Web 版 = Vite 开发服务器 + `dev-api.js` 后端中间件，在容器内提供完整管理功能。 --- -## Docker Compose 部署 +## 方式一：快速启动 -推荐使用 Docker Compose，配置更清晰，管理更方便。 - -### 1. 创建项目目录 +最简单的方式，一条命令搞定： ```bash -mkdir -p ~/openclaw && cd ~/openclaw +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 && \ + npx vite --port 1420 --host 0.0.0.0" ``` -### 2. 创建配置文件 +访问 `http://服务器IP:1420` 即可使用。 -```bash -cat > openclaw.json << 'EOF' -{ - "mode": "local", - "tools": { - "profile": "full", - "sessions": { - "visibility": "all" - } - }, - "gateway": { - "port": 18789, - "bind": "lan", - "auth": { - "mode": "token", - "token": "your-secret-token-change-me" - } - }, - "models": { - "providers": { - "deepseek": { - "baseUrl": "https://api.deepseek.com/v1", - "apiKey": "sk-your-api-key", - "models": [ - { "id": "deepseek-chat", "name": "DeepSeek V3" }, - { "id": "deepseek-reasoner", "name": "DeepSeek R1" } - ] - } - } - }, - "agents": { - "defaults": { - "model": { - "primary": "deepseek/deepseek-chat" - } - } - } -} -EOF -``` +> ⚠️ 这种方式每次重建容器都要重新 clone + npm install，适合快速体验。生产环境推荐使用 Compose 或自定义镜像。 -> 记得修改 `token` 和 `apiKey` 为你的实际值。 +--- -### 3. 创建 docker-compose.yml +## 方式二：Docker Compose（推荐） -```bash -cat > docker-compose.yml << 'EOF' +创建 `docker-compose.yml`： + +```yaml version: '3.8' services: - openclaw: + 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 + container_name: openclaw-gateway restart: unless-stopped ports: - "18789:18789" volumes: - - ./openclaw.json:/root/.openclaw/openclaw.json - openclaw-data:/root/.openclaw command: > - sh -c " - npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com 2>/dev/null; - openclaw gateway start - " - environment: - - NODE_ENV=production + 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: 10s + timeout: 5s retries: 3 - start_period: 60s volumes: openclaw-data: -EOF ``` -### 4. 启动 +同目录下创建 `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 + +CMD ["npx", "vite", "--port", "1420", "--host", "0.0.0.0"] +``` + +启动： ```bash docker compose up -d ``` -### 5. 查看日志 - -```bash -docker compose logs -f -``` - -看到 `Gateway listening on http://0.0.0.0:18789` 就说明启动成功了。 +这样 ClawPanel 和 Gateway 共享同一个 `openclaw-data` 卷，ClawPanel 可以直接管理 Gateway。 --- -## 使用自定义 Dockerfile（推荐生产环境） +## 方式三：自定义 Dockerfile -上面的方式每次容器重建都要重新 `npm install`，生产环境建议构建自定义镜像： +如果只需要 ClawPanel Web（Gateway 在宿主机或其他地方运行）： -### Dockerfile - -```bash -cat > Dockerfile << 'EOF' +```dockerfile FROM node:22-slim -# 安装 OpenClaw -RUN npm install -g @qingchencloud/openclaw-zh \ - --registry https://registry.npmmirror.com \ - && npm cache clean --force +RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/* -# 安装 curl 用于健康检查 -RUN apt-get update && apt-get install -y --no-install-recommends curl \ - && rm -rf /var/lib/apt/lists/* +# 安装 OpenClaw CLI（ClawPanel 需要读写配置） +RUN npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com -# 配置目录 -RUN mkdir -p /root/.openclaw -VOLUME /root/.openclaw +WORKDIR /app +RUN git clone https://github.com/qingchencloud/clawpanel.git . && \ + npm install -EXPOSE 18789 +EXPOSE 1420 -CMD ["openclaw", "gateway", "start"] -EOF +CMD ["npx", "vite", "--port", "1420", "--host", "0.0.0.0"] ``` -### docker-compose.yml（使用自定义镜像） +构建并运行： ```bash -cat > docker-compose.yml << 'EOF' -version: '3.8' - -services: - openclaw: - build: . - container_name: openclaw - restart: unless-stopped - ports: - - "18789:18789" - volumes: - - ./openclaw.json:/root/.openclaw/openclaw.json - - openclaw-data:/root/.openclaw - environment: - - NODE_ENV=production - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:18789/health"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 30s - -volumes: - openclaw-data: -EOF -``` - -```bash -# 构建并启动 -docker compose up -d --build -``` - -这样容器重启时直接启动 Gateway，无需重复安装。 - ---- - -## 配置说明 - -### 核心配置项 - -| 字段 | 说明 | 默认值 | -|------|------|--------| -| `mode` | 运行模式，必须设置 | `"local"` | -| `tools.profile` | Agent 工具权限 | `"full"` | -| `tools.sessions.visibility` | 会话可见性 | `"all"` | -| `gateway.port` | Gateway 监听端口 | `18789` | -| `gateway.bind` | 绑定范围 | `"lan"` | -| `gateway.auth.mode` | 认证方式 | `"token"` | -| `gateway.auth.token` | 访问密钥 | 无 | - -### bind 选项 - -| 值 | 说明 | -|------|------| -| `"loopback"` | 仅容器内部访问（127.0.0.1），Docker 环境下**不要用这个** | -| `"lan"` | 所有网卡（0.0.0.0），Docker 环境**必须用这个** | - -> ⚠️ Docker 容器内必须用 `"lan"`，否则端口映射无法工作。 - ---- - -## 模型配置 - -在 `openclaw.json` 的 `models.providers` 中添加服务商。以下是常见服务商示例： - -### DeepSeek - -```json -{ - "models": { - "providers": { - "deepseek": { - "baseUrl": "https://api.deepseek.com/v1", - "apiKey": "sk-xxxx", - "models": [ - { "id": "deepseek-chat", "name": "DeepSeek V3" }, - { "id": "deepseek-reasoner", "name": "DeepSeek R1" } - ] - } - } - } -} -``` - -### OpenAI - -```json -{ - "openai": { - "baseUrl": "https://api.openai.com/v1", - "apiKey": "sk-xxxx", - "models": [ - { "id": "gpt-4o", "name": "GPT-4o" }, - { "id": "gpt-4o-mini", "name": "GPT-4o Mini" } - ] - } -} -``` - -### Claude（通过兼容 API） - -```json -{ - "claude": { - "baseUrl": "https://your-claude-proxy.com/v1", - "apiKey": "sk-xxxx", - "models": [ - { "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4" } - ] - } -} -``` - -### Ollama（本地模型） - -```json -{ - "ollama": { - "baseUrl": "http://host.docker.internal:11434/v1", - "apiKey": "ollama", - "models": [ - { "id": "qwen2.5:14b", "name": "Qwen 2.5 14B" }, - { "id": "deepseek-r1:8b", "name": "DeepSeek R1 8B" } - ] - } -} -``` - -> 注意 Ollama 在 Docker 里要用 `host.docker.internal` 访问宿主机，Linux 下需要加 `--add-host=host.docker.internal:host-gateway`。 - -### Ollama + Docker 特殊配置 - -如果 Ollama 也运行在同一台机器上： - -```yaml -services: - openclaw: - # ... 其他配置 ... - extra_hosts: - - "host.docker.internal:host-gateway" -``` - -或者让 OpenClaw 和 Ollama 共享 Docker 网络： - -```yaml -services: - openclaw: - # ... 其他配置 ... - network_mode: host # 直接使用宿主机网络，Ollama 用 localhost:11434 - - # 或者 Ollama 也在 Compose 里 - ollama: - image: ollama/ollama - ports: - - "11434:11434" - volumes: - - ollama-data:/root/.ollama +docker build -t clawpanel . +docker run -d \ + --name clawpanel \ + --restart unless-stopped \ + -p 1420:1420 \ + -v ~/.openclaw:/root/.openclaw \ + clawpanel ``` --- -## 数据持久化 +## 配置与数据 -OpenClaw 的所有数据在 `/root/.openclaw` 目录： +### 数据目录 -| 路径 | 内容 | -|------|------| -| `openclaw.json` | 全局配置 | -| `agents/` | Agent 数据 | -| `memories/` | 记忆文件 | +ClawPanel 的所有数据都存储在 `~/.openclaw/` 目录中： + +| 文件/目录 | 说明 | +|-----------|------| +| `openclaw.json` | 主配置文件（模型、Gateway、Agent 设置） | +| `mcp.json` | MCP 服务器配置 | +| `logs/` | Gateway 日志 | | `backups/` | 配置备份 | +| `agents/` | Agent 数据（记忆、工作区） | +| `devices/` | 设备配对信息 | -通过 Docker Volume 或 bind mount 持久化： +### 持久化 -```yaml -# Docker Volume（推荐，Docker 自动管理） -volumes: - - openclaw-data:/root/.openclaw - -# Bind mount（挂载本地目录，方便直接编辑） -volumes: - - ./data:/root/.openclaw -``` - -### 备份 +使用 Docker Volume 或 Bind Mount 持久化数据： ```bash -# 备份整个数据目录 -docker cp openclaw:/root/.openclaw ./openclaw-backup-$(date +%Y%m%d) +# Docker Volume（推荐） +-v clawpanel-data:/root/.openclaw -# 仅备份配置 -docker cp openclaw:/root/.openclaw/openclaw.json ./openclaw.json.bak +# Bind Mount（方便直接查看文件） +-v ~/.openclaw:/root/.openclaw ``` +### 初始配置 + +首次启动如果没有 `openclaw.json`，可以先在容器内初始化： + +```bash +docker exec -it clawpanel openclaw init +``` + +或者将已有配置挂载进去。 + --- -## 网络与端口 +## 连接 Gateway -### 修改端口 +### 场景一：Gateway 在同一个 Compose 中 -```yaml -# docker-compose.yml -ports: - - "8080:18789" # 宿主机 8080 → 容器 18789 +使用上面的 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`。 -```json -{ - "gateway": { - "port": 8080 - } -} -``` +### 场景三：Gateway 在远程服务器 -```yaml -ports: - - "8080:8080" -``` - -### 使用 host 网络 - -```yaml -services: - openclaw: - network_mode: host - # 不需要 ports 映射，直接用宿主机端口 -``` - -适用于需要直接访问宿主机服务（如 Ollama）的场景。 +修改 `openclaw.json` 中的 Gateway 端口配置，或在 ClawPanel 面板中设置 Gateway 地址。 --- -## 反向代理 +## Nginx 反向代理 -### Nginx + Docker Compose - -```yaml -version: '3.8' - -services: - openclaw: - build: . - container_name: openclaw - restart: unless-stopped - volumes: - - ./openclaw.json:/root/.openclaw/openclaw.json - - openclaw-data:/root/.openclaw - # 不暴露端口到外部，只在内部网络 - - nginx: - image: nginx:alpine - container_name: openclaw-nginx - restart: unless-stopped - ports: - - "80:80" - - "443:443" - volumes: - - ./nginx.conf:/etc/nginx/conf.d/default.conf - - ./certs:/etc/nginx/certs - depends_on: - - openclaw - -volumes: - openclaw-data: -``` - -**nginx.conf：** +如果希望用域名 + HTTPS 访问： ```nginx server { listen 80; - server_name ai.example.com; - return 301 https://$host$request_uri; -} - -server { - listen 443 ssl http2; - server_name ai.example.com; - - ssl_certificate /etc/nginx/certs/fullchain.pem; - ssl_certificate_key /etc/nginx/certs/privkey.pem; + server_name panel.yourdomain.com; location / { - proxy_pass http://openclaw:18789; + 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 - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_read_timeout 86400; } } ``` +> **重要：** 必须配置 WebSocket 升级头，否则 ClawPanel 无法通过 `/ws` 连接 Gateway。 + --- ## 常用命令 ```bash -# 启动 -docker compose up -d - -# 停止 -docker compose down - -# 重启 -docker compose restart +# 查看状态 +docker ps | grep clawpanel # 查看日志 -docker compose logs -f - -# 查看最近 100 行日志 -docker compose logs --tail 100 +docker logs -f clawpanel # 进入容器 -docker exec -it openclaw sh - -# 查看容器状态 -docker compose ps - -# 重新构建并启动（修改了 Dockerfile 后） -docker compose up -d --build -``` - ---- - -## 升级 - -### 使用自定义 Dockerfile - -```bash -cd ~/openclaw - -# 重新构建镜像（会拉取最新版 OpenClaw） -docker compose build --no-cache +docker exec -it clawpanel bash # 重启 -docker compose up -d -``` +docker restart clawpanel -### 使用 node 基础镜像（容器内升级） - -```bash -# 进入容器 -docker exec -it openclaw sh - -# 升级 -npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com - -# 退出容器 -exit - -# 重启容器 -docker restart openclaw +# 停止并删除 +docker stop clawpanel && docker rm clawpanel ``` --- -## 多实例部署 +## 更新升级 -在同一台机器运行多个 OpenClaw 实例（不同端口、不同配置）： +### 更新 ClawPanel -```yaml -version: '3.8' +```bash +docker exec -it clawpanel bash -c "cd /app && git pull origin main && npm install" +docker restart clawpanel +``` -services: - openclaw-main: - build: . - container_name: openclaw-main - restart: unless-stopped - ports: - - "18789:18789" - volumes: - - ./config-main.json:/root/.openclaw/openclaw.json - - main-data:/root/.openclaw +### 使用 Compose 重建 - openclaw-dev: - build: . - container_name: openclaw-dev - restart: unless-stopped - ports: - - "18790:18789" - volumes: - - ./config-dev.json:/root/.openclaw/openclaw.json - - dev-data:/root/.openclaw +```bash +docker compose build --no-cache clawpanel +docker compose up -d clawpanel +``` -volumes: - main-data: - dev-data: +### 更新 OpenClaw + +```bash +docker exec -it clawpanel npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com ``` --- ## 常见问题 -### 容器启动后无法访问 +### Q: 容器启动后打开面板是空白？ -1. 确认 `gateway.bind` 是 `"lan"`（不是 `"loopback"`） -2. 检查端口映射：`docker compose ps` -3. 检查容器日志：`docker compose logs` -4. 检查防火墙是否放行端口 +检查容器日志： -### 首次启动很慢 - -首次启动需要 `npm install` 安装 OpenClaw，耗时 1-2 分钟。建议使用[自定义 Dockerfile](#使用自定义-dockerfile推荐生产环境) 方案，构建时安装，启动时直接运行。 - -### 容器重启后配置丢失 - -确保使用了 volume 持久化： - -```yaml -volumes: - - openclaw-data:/root/.openclaw +```bash +docker logs clawpanel ``` -或 bind mount 挂载本地目录。 +确认看到 `VITE ready` 和 `[dev-api] 开发 API 已启动` 输出。 -### 连接 Ollama 报错 +### Q: 面板显示 "openclaw.json 不存在"？ -Docker 容器内 `localhost` 是容器自己，不是宿主机。访问宿主机的 Ollama 需要： +在容器内初始化 OpenClaw： -```yaml -extra_hosts: - - "host.docker.internal:host-gateway" +```bash +docker exec -it clawpanel openclaw init ``` -然后 baseUrl 填 `http://host.docker.internal:11434/v1`。 +### Q: Gateway 按钮不工作（Docker 环境）？ -### 内存占用 +容器内管理 Gateway 进程需要特殊权限。推荐方案： -OpenClaw Gateway 本身约 50-100MB。如果同时运行 Ollama 等本地模型，建议 4GB+ 内存。 +1. **Compose 模式**：Gateway 作为独立容器运行，用 `docker compose restart gateway` 管理 +2. **Host 网络模式**：`--network host` 让 ClawPanel 直接管理宿主机进程 -### 时区问题 +### Q: 数据会丢失吗？ -```yaml -services: - openclaw: - environment: - - TZ=Asia/Shanghai -``` +只要正确配置了 Volume 挂载（`-v clawpanel-data:/root/.openclaw`），容器删除重建不会丢失数据。 ---- +### Q: 与桌面版有什么区别？ -## 完整示例 - -生产就绪的 docker-compose.yml： - -```yaml -version: '3.8' - -services: - openclaw: - build: . - container_name: openclaw - restart: unless-stopped - ports: - - "18789:18789" - volumes: - - ./openclaw.json:/root/.openclaw/openclaw.json - - openclaw-data:/root/.openclaw - environment: - - NODE_ENV=production - - TZ=Asia/Shanghai - healthcheck: - test: ["CMD", "curl", "-f", "http://localhost:18789/health"] - interval: 30s - timeout: 10s - retries: 3 - start_period: 30s - deploy: - resources: - limits: - memory: 512M - logging: - driver: json-file - options: - max-size: "10m" - max-file: "3" - -volumes: - openclaw-data: -``` +| 功能 | 桌面版 (Win/Mac) | Docker Web 版 | +|------|-----------------|---------------| +| 配置管理 | ✅ | ✅ | +| Gateway 管理 | ✅ | ⚠️ 需 host 网络或 Compose | +| 模型测试 | ✅ | ✅ | +| 日志查看 | ✅ | ✅ | +| 备份管理 | ✅ | ✅ | +| Agent 记忆 | ✅ | ✅ | +| ZIP 导出 | ✅ | ❌ | +| 系统托盘 | ✅ | ❌ | +| 自动更新 | ✅ | 手动重建镜像 | diff --git a/docs/index.html b/docs/index.html index cf5f61f..88eee9e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -727,7 +727,7 @@

服务器 部署指南

-

不用桌面环境，在 Linux 服务器或 Docker 上一键部署 OpenClaw Gateway

+

没有桌面环境？在 Linux 或 Docker 上部署 ClawPanel Web 版，浏览器即可管理 OpenClaw

@@ -747,7 +747,7 @@ bash
-
# 一键安装 Node.js + OpenClaw + systemd 自启
+
# 一键部署 ClawPanel Web + OpenClaw + systemd 自启
curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash
@@ -756,7 +756,7 @@ 完整教程 - Node.js 安装 · 配置模型 · systemd/PM2 · Nginx 反代 · 防火墙 + Node.js · OpenClaw · systemd/PM2 · Nginx 反代 · 防火墙 @@ -767,7 +767,7 @@

Docker 部署

-

容器化隔离，支持 Compose 编排、Nginx 反代、Ollama 联动

+

容器化隔离，支持 Compose 编排、自定义镜像、Nginx 反代

@@ -776,10 +776,10 @@ bash
-
# 一条命令启动 Gateway
-
docker run -d --name openclaw --restart unless-stopped \
-
-p 18789:18789 -v openclaw-data:/root/.openclaw \
-
node:22-slim sh -c "npm i -g @qingchencloud/openclaw-zh && openclaw gateway start"
+
# 一条命令启动 ClawPanel Web
+
docker run -d --name clawpanel -p 1420:1420 \
+
-v clawpanel-data:/root/.openclaw node:22-slim \
+
sh -c "apt-get update && apt-get install -y git && ..."
@@ -787,14 +787,14 @@ 完整教程 - Compose · Dockerfile · 模型配置 · Ollama · 多实例 + Compose · Dockerfile · Gateway 联动 · Nginx 反代

- 部署完成后，用 ClawPanel 连接 http://服务器IP:18789 即可远程管理模型、Agent、日志等。手机端可用 ClawApp。 + 部署完成后，访问 http://服务器IP:1420 即可通过浏览器管理 OpenClaw，功能与桌面版一致。

@@ -813,7 +813,7 @@
🖥️

Linux 部署指南

-

从零开始在 Linux 服务器上部署 OpenClaw Gateway，一键脚本 + 手动安装两种方式

+

在 Linux 服务器上部署 ClawPanel Web 版，通过浏览器远程管理 OpenClaw

一键部署 systemd @@ -826,12 +826,12 @@
🐳

Docker 部署指南

-

容器化部署 OpenClaw，支持 Compose 编排、自定义镜像、Ollama 联动、多实例

+

用 Docker 部署 ClawPanel Web 版，支持 Compose 编排、自定义镜像、Gateway 联动

Docker Compose Dockerfile - Ollama - 反向代理 + Gateway 联动 + Nginx 反代
diff --git a/docs/linux-deploy.md b/docs/linux-deploy.md index 71f05f4..57dd3fc 100644 --- a/docs/linux-deploy.md +++ b/docs/linux-deploy.md @@ -1,638 +1,385 @@ -# Linux 服务器部署指南 +# ClawPanel Linux 部署指南 -本文介绍如何在 Linux 服务器上部署 OpenClaw，从零到跑通只需 5 分钟。 +本文介绍如何在 Linux 服务器上部署 **ClawPanel Web 版**，通过浏览器远程管理 OpenClaw。 适用场景：云服务器、NAS、家庭 HomeLab、无 GUI 的 Linux 主机。 +> **ClawPanel** 有 Win/Mac 桌面客户端，但 Linux 没有桌面版。Web 版通过 Vite + Node.js 后端运行，功能与桌面版一致。 + +--- + ## 目录 -- [一键部署](#一键部署) -- [分步安装](#分步安装) -- [配置模型](#配置模型) -- [启动 Gateway](#启动-gateway) -- [开机自启](#开机自启) -- [远程管理](#远程管理) -- [反向代理](#反向代理) +- [架构说明](#架构说明) +- [前提条件](#前提条件) +- [方式一：一键部署](#方式一一键部署) +- [方式二：手动部署](#方式二手动部署) +- [方式三：Docker 部署](#方式三docker-部署) +- [访问 ClawPanel](#访问-clawpanel) +- [进程守护](#进程守护) +- [Nginx 反向代理](#nginx-反向代理) +- [防火墙配置](#防火墙配置) +- [更新升级](#更新升级) - [常见问题](#常见问题) --- -## 一键部署 +## 架构说明 -复制以下命令到终端，一键完成 Node.js + OpenClaw 安装、配置、启动： +``` +浏览器 ──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 ``` -> 脚本会自动检测系统环境，安装 Node.js（如未安装），安装 OpenClaw 汉化版，配置默认参数，启动 Gateway。 +脚本自动完成： +1. 检测系统、安装 Node.js（如果缺少） +2. 安装 OpenClaw 汉化版（如果缺少） +3. 克隆 ClawPanel 仓库、安装依赖 +4. 创建 systemd 服务、开机自启 +5. 启动 ClawPanel Web，输出访问地址 -不想用一键脚本？往下看分步安装。 +部署完成后访问 `http://服务器IP:1420`。 --- -## 分步安装 +## 方式二：手动部署 ### 1. 安装 Node.js -OpenClaw 需要 Node.js >= 18。选择适合你的安装方式： - -**方式一：包管理器（推荐）** +**Ubuntu / Debian：** ```bash -# Ubuntu / Debian curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs - -# CentOS / RHEL / Fedora -curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - -sudo yum install -y nodejs - -# Alpine -apk add nodejs npm ``` -**方式二：nvm（多版本管理）** +**CentOS / RHEL / Fedora：** ```bash -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash -source ~/.bashrc -nvm install 22 +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 # 应显示 v18+ 版本号 -npm -v # 应显示 npm 版本号 +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 - -# 或使用官方源 -npm install -g @qingchencloud/openclaw-zh ``` -验证安装： +初始化配置（首次）： ```bash -openclaw --version +openclaw init ``` -### 3. 初始化配置 +### 3. 克隆 ClawPanel ```bash -# 创建配置目录 -mkdir -p ~/.openclaw - -# 写入基础配置 -cat > ~/.openclaw/openclaw.json << 'EOF' -{ - "mode": "local", - "tools": { - "profile": "full", - "sessions": { - "visibility": "all" - } - }, - "gateway": { - "port": 18789, - "bind": "lan", - "auth": {} - }, - "models": { - "providers": {} - } -} -EOF +cd /opt +sudo git clone https://github.com/qingchencloud/clawpanel.git +sudo chown -R $(whoami) clawpanel +cd clawpanel +npm install ``` -**配置说明：** - -| 字段 | 值 | 说明 | -|------|------|------| -| `mode` | `"local"` | 运行模式，必须设置 | -| `tools.profile` | `"full"` | Agent 工具权限，`full` 为全部开启 | -| `gateway.port` | `18789` | Gateway 监听端口 | -| `gateway.bind` | `"lan"` | `"loopback"` 仅本机 / `"lan"` 局域网可访问 | -| `gateway.auth` | `{}` | 认证配置，生产环境建议设置 Token | - -**设置访问密钥（推荐）：** - -如果你的服务器有公网 IP 或局域网内有其他设备访问，强烈建议设置 Token： +### 4. 启动 ClawPanel Web ```bash -# 用 jq 修改（需安装 jq） -jq '.gateway.auth = {"mode": "token", "token": "你的密钥"}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json +npx vite --port 1420 --host 0.0.0.0 +``` -# 或直接编辑 -nano ~/.openclaw/openclaw.json +看到以下输出即为成功： + +``` + VITE v6.x.x ready in xxx ms + + ➜ Local: http://localhost:1420/ + ➜ Network: http://xxx.xxx.xxx.xxx:1420/ + [dev-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 && npx vite --port 1420 --host 0.0.0.0" ``` --- -## 配置模型 +## 访问 ClawPanel -OpenClaw 需要至少一个 AI 模型才能使用。编辑 `~/.openclaw/openclaw.json`，在 `models.providers` 中添加服务商： +部署完成后，用浏览器打开： -### 示例：添加 OpenAI 兼容服务商 - -```bash -cat > /tmp/add-provider.py << 'PYEOF' -import json, sys -config_path = f"{sys.path[0]}/../.openclaw/openclaw.json".replace(sys.path[0] + "/../", "") -import os -config_path = os.path.expanduser("~/.openclaw/openclaw.json") -with open(config_path) as f: - config = json.load(f) - -# 修改为你的实际服务商信息 -provider_id = "my-provider" -config["models"]["providers"][provider_id] = { - "baseUrl": "https://api.openai.com/v1", - "apiKey": "sk-xxxx", - "models": [ - {"id": "gpt-4o", "name": "GPT-4o"}, - {"id": "gpt-4o-mini", "name": "GPT-4o Mini"} - ] -} - -# 设置默认模型 -config.setdefault("agents", {}).setdefault("defaults", {})["model"] = { - "primary": f"{provider_id}/gpt-4o" -} - -with open(config_path, "w") as f: - json.dump(config, f, indent=2, ensure_ascii=False) - -print(f"✅ 已添加服务商 {provider_id}") -PYEOF -python3 /tmp/add-provider.py +``` +http://服务器IP:1420 ``` -**或者直接编辑 JSON（更直观）：** - -```bash -nano ~/.openclaw/openclaw.json -``` - -在 `models.providers` 中加入： - -```json -{ - "models": { - "providers": { - "my-provider": { - "baseUrl": "https://api.openai.com/v1", - "apiKey": "sk-xxxx", - "models": [ - { "id": "gpt-4o", "name": "GPT-4o" }, - { "id": "gpt-4o-mini", "name": "GPT-4o Mini" } - ] - } - } - } -} -``` - -> 支持任何 OpenAI 兼容 API（DeepSeek、通义千问、智谱、Ollama 等），只需修改 `baseUrl` 和 `apiKey`。 +ClawPanel 会自动检测本机的 OpenClaw 安装，你可以： +- 管理模型配置（添加/删除/测试 Provider） +- 启动/停止/重启 Gateway +- 查看 Gateway 日志 +- 管理 Agent 记忆文件 +- 配置备份与恢复 --- -## 启动 Gateway +## 进程守护 -### 前台运行（调试用） - -```bash -openclaw gateway start -``` - -看到类似输出说明启动成功： - -``` -Gateway listening on http://0.0.0.0:18789 -``` - -按 `Ctrl+C` 停止。 - -### 后台运行 - -```bash -# 使用 nohup -nohup openclaw gateway start > ~/.openclaw/gateway.log 2>&1 & -echo $! > ~/.openclaw/gateway.pid - -# 查看日志 -tail -f ~/.openclaw/gateway.log - -# 停止 -kill $(cat ~/.openclaw/gateway.pid) -``` - -### 验证运行 - -```bash -# 检查端口是否在监听 -ss -tlnp | grep 18789 - -# 测试 API 响应 -curl http://localhost:18789/health - -# 从其他机器测试（替换为服务器 IP） -curl http://你的服务器IP:18789/health -``` - ---- - -## 开机自启 +前台运行会在终端关闭后退出，推荐用 systemd 或 PM2 保持常驻。 ### 方式一：systemd（推荐） +创建服务文件： + ```bash -sudo tee /etc/systemd/system/openclaw.service << EOF +sudo tee /etc/systemd/system/clawpanel.service << 'EOF' [Unit] -Description=OpenClaw Gateway +Description=ClawPanel Web - OpenClaw Management Panel After=network.target [Service] Type=simple -User=$USER -Environment=PATH=$(dirname $(which node)):$PATH -ExecStart=$(which openclaw) gateway start +User=root +WorkingDirectory=/opt/clawpanel +ExecStart=/usr/bin/npx vite --port 1420 --host 0.0.0.0 Restart=on-failure RestartSec=5 -WorkingDirectory=$HOME +Environment=NODE_ENV=production [Install] WantedBy=multi-user.target EOF - -# 启用并启动 -sudo systemctl daemon-reload -sudo systemctl enable openclaw -sudo systemctl start openclaw - -# 查看状态 -sudo systemctl status openclaw - -# 查看日志 -journalctl -u openclaw -f ``` -**常用命令：** +启用并启动： ```bash -sudo systemctl start openclaw # 启动 -sudo systemctl stop openclaw # 停止 -sudo systemctl restart openclaw # 重启 -sudo systemctl status openclaw # 查看状态 -journalctl -u openclaw -f # 实时日志 +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 -# 安装 PM2 npm install -g pm2 -# 启动 -pm2 start "openclaw gateway start" --name openclaw - -# 设置开机自启 +cd /opt/clawpanel +pm2 start "npx vite --port 1420 --host 0.0.0.0" --name clawpanel pm2 save -pm2 startup - -# 常用命令 -pm2 status # 查看状态 -pm2 logs openclaw # 查看日志 -pm2 restart openclaw -pm2 stop openclaw +pm2 startup # 开机自启 ``` -### 方式三：Docker（适合隔离部署） - -```bash -docker run -d \ - --name openclaw \ - --restart unless-stopped \ - -p 18789:18789 \ - -v ~/.openclaw:/root/.openclaw \ - node:22-slim \ - sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && openclaw gateway start" -``` - -> 📖 Docker 完整教程（Compose、自定义镜像、Nginx 反向代理、Ollama 联动等）见 [Docker 部署指南](docker-deploy.md) - --- -## 远程管理 +## Nginx 反向代理 -Gateway 启动后，你可以通过以下方式管理： - -### 方式一：ClawPanel 桌面端远程连接 - -在你的 Windows/Mac 电脑上安装 [ClawPanel](https://github.com/qingchencloud/clawpanel/releases/latest)，打开后在 Gateway 配置页选择「云端模式」，填入服务器地址即可远程管理。 - -### 方式二：ClawApp 移动端 - -用手机上的 [ClawApp](https://github.com/qingchencloud/clawapp) 连接 Gateway 地址，随时随地与 AI 对话。 - -### 方式三：API 直接调用 - -Gateway 兼容 OpenAI API 格式，任何支持 OpenAI API 的客户端都可以直连： - -```bash -# 对话测试 -curl http://你的服务器IP:18789/v1/chat/completions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer 你的Token" \ - -d '{ - "model": "gpt-4o", - "messages": [{"role": "user", "content": "你好"}] - }' -``` - -**在第三方客户端中使用：** - -| 设置项 | 值 | -|--------|------| -| API Base URL | `http://服务器IP:18789/v1` | -| API Key | 你在 `gateway.auth.token` 中设置的密钥 | -| Model | 你配置的模型 ID（如 `gpt-4o`） | - -支持 Cherry Studio、ChatBox、LobeChat、BotGem 等所有兼容 OpenAI API 的客户端。 - ---- - -## 反向代理 - -生产环境建议用 Nginx 反向代理，加上 HTTPS。 - -### Nginx 配置 +如果希望用域名 + HTTPS 访问 ClawPanel： ```nginx server { - listen 443 ssl http2; - server_name ai.example.com; - - ssl_certificate /etc/ssl/certs/ai.example.com.pem; - ssl_certificate_key /etc/ssl/private/ai.example.com.key; + listen 80; + server_name panel.yourdomain.com; location / { - proxy_pass http://127.0.0.1:18789; + 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 支持（聊天流式响应需要） - proxy_http_version 1.1; - proxy_set_header Upgrade $http_upgrade; - proxy_set_header Connection "upgrade"; - proxy_read_timeout 86400; } } ``` -```bash -sudo nginx -t && sudo systemctl reload nginx -``` +> **重要：** 必须配置 WebSocket 升级（`Upgrade` + `Connection`），否则 ClawPanel 无法连接 Gateway。 -配置完成后，用 `https://ai.example.com` 替代 IP + 端口访问。 - -### Cloudflare Tunnel（无需公网 IP） - -如果你的服务器没有公网 IP，可以用 [cftunnel](https://github.com/qingchencloud/cftunnel) 一键穿透： +配合 Let's Encrypt 启用 HTTPS： ```bash -# 安装 cftunnel -npm install -g cftunnel - -# 创建隧道 -cftunnel create --name my-ai --hostname ai.example.com --url http://localhost:18789 - -# 启动 -cftunnel start +sudo apt install certbot python3-certbot-nginx +sudo certbot --nginx -d panel.yourdomain.com ``` --- -## 防火墙 +## 防火墙配置 -如果需要外部访问，记得开放端口： +### UFW (Ubuntu/Debian) ```bash -# UFW（Ubuntu） -sudo ufw allow 18789/tcp +sudo ufw allow 1420/tcp # ClawPanel Web +sudo ufw allow 18789/tcp # OpenClaw Gateway（如需外部直连） +``` -# firewalld（CentOS / Fedora） -sudo firewall-cmd --permanent --add-port=18789/tcp +### firewalld (CentOS/RHEL) + +```bash +sudo firewall-cmd --permanent --add-port=1420/tcp sudo firewall-cmd --reload - -# iptables -sudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPT ``` -> 如果使用了 Nginx 反向代理，只需开放 80/443 端口，不需要开放 18789。 - --- -## 升级 +## 更新升级 + +### 更新 ClawPanel ```bash -# 升级 OpenClaw -npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com - -# 重启服务 -sudo systemctl restart openclaw -# 或 -pm2 restart openclaw +cd /opt/clawpanel +git pull origin main +npm install +sudo systemctl restart clawpanel # 或 pm2 restart clawpanel ``` +### 更新 OpenClaw + +```bash +npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com +``` + +或在 ClawPanel 面板中点击「检查更新」按钮。 + --- ## 常见问题 -### npm install 报错 EACCES（权限不足） +### Q: 端口 1420 被占用？ ```bash -# 方式一：修复 npm 全局目录权限 -mkdir -p ~/.npm-global -npm config set prefix '~/.npm-global' -echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc -source ~/.bashrc +# 查看占用 +lsof -i :1420 -# 然后重新安装 -npm install -g @qingchencloud/openclaw-zh +# 使用其他端口 +npx vite --port 3000 --host 0.0.0.0 ``` -### Gateway 启动后外部无法访问 +systemd 服务也需要改 ExecStart 中的端口。 -1. 检查 `gateway.bind` 是否为 `"lan"`（不要用 `"loopback"`） -2. 检查防火墙是否放行了端口 -3. 云服务器检查安全组规则是否开放端口 +### Q: 打开面板显示 "openclaw.json 不存在"？ + +需要先安装 OpenClaw 并初始化： ```bash -# 验证监听地址 -ss -tlnp | grep 18789 -# 应显示 0.0.0.0:18789，而不是 127.0.0.1:18789 -``` - -### 端口被占用 - -```bash -# 查看谁占了端口 -sudo lsof -i :18789 - -# 改用其他端口 -jq '.gateway.port = 18790' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json -``` - -### Node.js 版本太低 - -```bash -node -v -# 如果低于 v18，需要升级 - -# 使用 nvm 升级 -nvm install 22 -nvm alias default 22 -``` - -### 内存不足 - -OpenClaw Gateway 本身占用很小（约 50-100MB），但如果你同时运行 Ollama 等本地模型，建议至少 4GB 内存。 - ---- - -## 完整配置参考 - -```json -{ - "mode": "local", - "tools": { - "profile": "full", - "sessions": { - "visibility": "all" - } - }, - "gateway": { - "port": 18789, - "bind": "lan", - "mode": "local", - "auth": { - "mode": "token", - "token": "your-secret-token" - } - }, - "models": { - "providers": { - "deepseek": { - "baseUrl": "https://api.deepseek.com/v1", - "apiKey": "sk-xxxx", - "models": [ - { "id": "deepseek-chat", "name": "DeepSeek V3" }, - { "id": "deepseek-reasoner", "name": "DeepSeek R1" } - ] - } - } - }, - "agents": { - "defaults": { - "model": { - "primary": "deepseek/deepseek-chat" - } - } - } -} -``` - ---- - -## 一键部署脚本参考 - -不想记那么多命令？保存以下脚本到服务器，一键搞定： - -```bash -#!/bin/bash -set -e - -echo "==========================================" -echo " OpenClaw 一键部署脚本" -echo "==========================================" - -# 检查 Node.js -if ! command -v node &> /dev/null || [ "$(node -v | sed 's/v//' | cut -d. -f1)" -lt 18 ]; then - echo "📦 安装 Node.js 22..." - curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - - sudo apt-get install -y nodejs -fi -echo "✅ Node.js $(node -v)" - -# 安装 OpenClaw -echo "📦 安装 OpenClaw..." npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com -echo "✅ OpenClaw $(openclaw --version)" - -# 初始化配置 -mkdir -p ~/.openclaw -if [ ! -f ~/.openclaw/openclaw.json ]; then - echo "📝 写入默认配置..." - cat > ~/.openclaw/openclaw.json << 'CONF' -{ - "mode": "local", - "tools": { "profile": "full", "sessions": { "visibility": "all" } }, - "gateway": { "port": 18789, "bind": "lan", "auth": {} }, - "models": { "providers": {} } -} -CONF -fi - -# 创建 systemd 服务 -echo "⚙️ 配置开机自启..." -sudo tee /etc/systemd/system/openclaw.service > /dev/null << SVCEOF -[Unit] -Description=OpenClaw Gateway -After=network.target - -[Service] -Type=simple -User=$USER -Environment=PATH=$(dirname $(which node)):$PATH -ExecStart=$(which openclaw) gateway start -Restart=on-failure -RestartSec=5 -WorkingDirectory=$HOME - -[Install] -WantedBy=multi-user.target -SVCEOF - -sudo systemctl daemon-reload -sudo systemctl enable openclaw -sudo systemctl start openclaw - -echo "" -echo "==========================================" -echo " ✅ 部署完成！" -echo "==========================================" -echo "" -echo " Gateway 地址: http://$(hostname -I | awk '{print $1}'):18789" -echo "" -echo " 管理命令:" -echo " sudo systemctl status openclaw # 查看状态" -echo " sudo systemctl restart openclaw # 重启" -echo " journalctl -u openclaw -f # 查看日志" -echo "" -echo " 下一步:" -echo " 1. 编辑 ~/.openclaw/openclaw.json 添加你的模型 API Key" -echo " 2. sudo systemctl restart openclaw" -echo " 3. 用 ClawPanel 或 ClawApp 连接 Gateway" -echo "" +openclaw init ``` -保存为 `deploy.sh`，然后 `chmod +x deploy.sh && ./deploy.sh`。 +### 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 +npx vite --port 1420 --host 0.0.0.0 +``` + +或者用 systemd 分别创建两个服务。也可以在 ClawPanel 面板中直接点击「启动」按钮管理 Gateway。 + +### Q: 与桌面版有什么区别？ + +| 功能 | 桌面版 (Win/Mac) | Web 版 (Linux) | +|------|-----------------|----------------| +| 配置管理 | ✅ | ✅ | +| Gateway 管理 | ✅ | ✅ | +| 模型测试 | ✅ | ✅ | +| 日志查看 | ✅ | ✅ | +| 备份管理 | ✅ | ✅ | +| Agent 记忆 | ✅ | ✅ | +| ZIP 导出 | ✅ | ❌ | +| 系统托盘 | ✅ | ❌ | +| 自动更新 | ✅ | 手动 git pull | diff --git a/scripts/linux-deploy.sh b/scripts/linux-deploy.sh index 07f5b5f..cfbf8af 100644 --- a/scripts/linux-deploy.sh +++ b/scripts/linux-deploy.sh @@ -2,10 +2,16 @@ set -e echo "==========================================" -echo " OpenClaw 一键部署脚本" +echo " ClawPanel Web 版 一键部署脚本" +echo " 在 Linux 上通过浏览器管理 OpenClaw" echo "==========================================" echo "" +INSTALL_DIR="/opt/clawpanel" +PANEL_PORT=1420 +REPO_URL="https://github.com/qingchencloud/clawpanel.git" +NPM_REGISTRY="https://registry.npmmirror.com" + # 检测系统 detect_os() { if [ -f /etc/os-release ]; then @@ -28,212 +34,163 @@ install_node() { echo "✅ Node.js $(node -v) 已安装" return 0 else - echo "⚠️ Node.js 版本过低 ($(node -v))，需要 >= 18" + echo "⚠️ Node.js $(node -v) 版本过低，需要 18+" fi fi - echo "📦 安装 Node.js 22..." - + echo "📦 安装 Node.js 22 LTS..." case "$OS" in ubuntu|debian|linuxmint|pop) curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs ;; - centos|rhel|fedora|rocky|alma|opencloudos) + centos|rhel|fedora|rocky|alma) curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - - sudo yum install -y nodejs || sudo dnf install -y nodejs + sudo yum install -y nodejs ;; alpine) - sudo apk add nodejs npm + sudo apk add nodejs npm git ;; arch|manjaro) - sudo pacman -S --noconfirm nodejs npm + sudo pacman -Sy --noconfirm nodejs npm git ;; *) - # 通用方式：使用 nvm - echo "🔧 未识别的发行版，使用 nvm 安装..." - if ! command -v nvm &> /dev/null; then - curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash - export NVM_DIR="$HOME/.nvm" - [ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh" - fi - nvm install 22 - nvm alias default 22 + echo "❌ 不支持自动安装 Node.js，请手动安装后重试" + echo " 参考: https://nodejs.org/en/download/" + exit 1 ;; esac + echo "✅ Node.js $(node -v) 安装完成" +} - echo "✅ Node.js $(node -v) 安装成功" +# 安装 Git +install_git() { + if command -v git &> /dev/null; then + echo "✅ Git 已安装" + return 0 + fi + + echo "📦 安装 Git..." + case "$OS" in + ubuntu|debian|linuxmint|pop) + sudo apt-get update && sudo apt-get install -y git + ;; + centos|rhel|fedora|rocky|alma) + sudo yum install -y git + ;; + alpine) + sudo apk add git + ;; + arch|manjaro) + sudo pacman -Sy --noconfirm git + ;; + esac + echo "✅ Git 安装完成" } # 安装 OpenClaw install_openclaw() { - echo "📦 安装 OpenClaw 汉化版..." - - # 检查是否需要修复 npm 权限 - local npm_prefix=$(npm config get prefix 2>/dev/null || echo "/usr/local") - if [ ! -w "$npm_prefix/lib" ] 2>/dev/null; then - # 无写入权限，使用用户目录 - if [ "$(id -u)" -ne 0 ]; then - echo "🔧 配置 npm 用户目录..." - mkdir -p ~/.npm-global - npm config set prefix '~/.npm-global' - export PATH=~/.npm-global/bin:$PATH - if ! grep -q '.npm-global/bin' ~/.bashrc 2>/dev/null; then - echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc - fi - fi - fi - - npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com - - # 验证 if command -v openclaw &> /dev/null; then - echo "✅ OpenClaw $(openclaw --version) 安装成功" + echo "✅ OpenClaw 已安装: $(openclaw --version 2>/dev/null || echo '未知版本')" else - echo "❌ openclaw 命令未找到，请检查 PATH" - echo " 尝试: source ~/.bashrc && openclaw --version" - exit 1 + echo "📦 安装 OpenClaw 汉化版..." + npm install -g @qingchencloud/openclaw-zh --registry "$NPM_REGISTRY" + echo "✅ OpenClaw 安装完成" + fi + + # 初始化配置（如果不存在） + if [ ! -f "$HOME/.openclaw/openclaw.json" ]; then + echo "🔧 初始化 OpenClaw 配置..." + openclaw init 2>/dev/null || true fi } -# 初始化配置 -init_config() { - mkdir -p ~/.openclaw - - if [ -f ~/.openclaw/openclaw.json ]; then - echo "✅ 配置文件已存在，跳过初始化" - return 0 +# 克隆并安装 ClawPanel +install_clawpanel() { + if [ -d "$INSTALL_DIR" ] && [ -f "$INSTALL_DIR/package.json" ]; then + echo "📦 ClawPanel 已存在，更新中..." + cd "$INSTALL_DIR" + git pull origin main 2>/dev/null || true + npm install + else + echo "📦 克隆 ClawPanel..." + sudo mkdir -p "$INSTALL_DIR" + sudo chown -R $(whoami) "$INSTALL_DIR" + git clone "$REPO_URL" "$INSTALL_DIR" + cd "$INSTALL_DIR" + npm install fi - - echo "📝 写入默认配置..." - cat > ~/.openclaw/openclaw.json << 'EOF' -{ - "mode": "local", - "tools": { - "profile": "full", - "sessions": { - "visibility": "all" - } - }, - "gateway": { - "port": 18789, - "bind": "lan", - "auth": {} - }, - "models": { - "providers": {} - } -} -EOF - - echo "✅ 配置已写入 ~/.openclaw/openclaw.json" + echo "✅ ClawPanel 安装完成: $INSTALL_DIR" } -# 安装 systemd 服务 -install_service() { - # 检查 systemd 是否可用 +# 创建 systemd 服务 +setup_systemd() { if ! command -v systemctl &> /dev/null; then - echo "⚠️ systemd 不可用，使用 nohup 后台启动..." - nohup openclaw gateway start > ~/.openclaw/gateway.log 2>&1 & - echo $! > ~/.openclaw/gateway.pid - echo "✅ Gateway 已后台启动 (PID: $(cat ~/.openclaw/gateway.pid))" + echo "⚠️ systemd 不可用，请手动启动：" + echo " cd $INSTALL_DIR && npx vite --port $PANEL_PORT --host 0.0.0.0" return 0 fi - echo "⚙️ 配置 systemd 服务..." - - local node_path=$(dirname $(which node)) - local openclaw_path=$(which openclaw) - - sudo tee /etc/systemd/system/openclaw.service > /dev/null << SVCEOF + echo "🔧 创建 systemd 服务..." + sudo tee /etc/systemd/system/clawpanel.service > /dev/null << EOF [Unit] -Description=OpenClaw Gateway +Description=ClawPanel Web - OpenClaw Management Panel After=network.target [Service] Type=simple -User=$USER -Environment=PATH=$node_path:/usr/local/bin:/usr/bin:/bin -ExecStart=$openclaw_path gateway start +User=$(whoami) +WorkingDirectory=$INSTALL_DIR +ExecStart=$(which npx) vite --port $PANEL_PORT --host 0.0.0.0 Restart=on-failure RestartSec=5 -WorkingDirectory=$HOME +Environment=NODE_ENV=production +Environment=HOME=$HOME [Install] WantedBy=multi-user.target -SVCEOF +EOF sudo systemctl daemon-reload - sudo systemctl enable openclaw - sudo systemctl start openclaw - - # 等待启动 - sleep 3 - if sudo systemctl is-active --quiet openclaw; then - echo "✅ Gateway 服务已启动并设为开机自启" - else - echo "⚠️ Gateway 服务可能未启动，请检查: journalctl -u openclaw -n 20" - fi + sudo systemctl enable clawpanel + sudo systemctl start clawpanel + echo "✅ systemd 服务已创建并启动" } -# 获取服务器 IP -get_server_ip() { - local ip=$(hostname -I 2>/dev/null | awk '{print $1}') - if [ -z "$ip" ]; then - ip=$(ip route get 1 2>/dev/null | awk '{print $7; exit}') - fi - if [ -z "$ip" ]; then - ip="localhost" - fi - echo "$ip" +# 获取本机 IP +get_local_ip() { + ip route get 1 2>/dev/null | awk '{print $7; exit}' || \ + hostname -I 2>/dev/null | awk '{print $1}' || \ + echo "localhost" } # 主流程 main() { detect_os echo "" - + install_git install_node - echo "" - install_openclaw + install_clawpanel + setup_systemd + + local ip=$(get_local_ip) echo "" - - init_config - echo "" - - install_service - echo "" - - local server_ip=$(get_server_ip) - local port=$(grep -o '"port":[[:space:]]*[0-9]*' ~/.openclaw/openclaw.json 2>/dev/null | head -1 | grep -o '[0-9]*' || echo "18789") - echo "==========================================" - echo " ✅ 部署完成！" + echo " ✅ ClawPanel Web 版部署完成！" echo "==========================================" echo "" - echo " Gateway 地址: http://${server_ip}:${port}" + echo " 🌐 访问地址: http://${ip}:${PANEL_PORT}" + echo " 📁 安装目录: $INSTALL_DIR" + echo " 📋 配置目录: $HOME/.openclaw/" echo "" - echo " 管理命令:" - if command -v systemctl &> /dev/null; then - echo " sudo systemctl status openclaw # 查看状态" - echo " sudo systemctl restart openclaw # 重启" - echo " journalctl -u openclaw -f # 查看日志" - else - echo " cat ~/.openclaw/gateway.pid # 查看 PID" - echo " tail -f ~/.openclaw/gateway.log # 查看日志" - echo " kill \$(cat ~/.openclaw/gateway.pid) # 停止" - fi - echo "" - echo " 下一步:" - echo " 1. 编辑 ~/.openclaw/openclaw.json 添加模型 API Key" - if command -v systemctl &> /dev/null; then - echo " 2. sudo systemctl restart openclaw" - else - echo " 2. 重启 Gateway" - fi - echo " 3. 用 ClawPanel 或 ClawApp 连接管理" + echo " 常用命令：" + echo " systemctl status clawpanel # 查看状态" + echo " systemctl restart clawpanel # 重启面板" + echo " journalctl -u clawpanel -f # 查看日志" echo "" + echo " 用浏览器打开上面的地址，即可管理 OpenClaw。" + echo "==========================================" } main "$@"