创建一个工作目录

为了确保清晰,本教程将分为几个部分，并提供两种主流安装方式：Docker 快速安装 和 源码/包安装。

第一部分：准备环境

在开始之前,请确保您的服务器满足以下条件：

1. 操作系统：Linux（CentOS 7/8， Ubuntu 18.04/20.04/22.04 等）、macOS 或 Windows（对于开发，生产环境推荐 Linux）。
2. Docker 和 Docker Compose（如果选择Docker方式）：这是最推荐、最简单的方式。

   # 检查是否安装
   docker --version
   docker-compose --version

3. 如果不用Docker：
   • OpenResty：版本 >= 1.19.3.1
   • etcd：版本 >= 3.4.0（APISIX 默认使用 etcd 作为配置中心）
   • curl， git， gcc， make 等编译工具。

---

第二部分：安装方式一：使用 Docker 快速启动（推荐）

这是最简单、最不易出错的方式，尤其适合测试和快速部署。

步骤 1：获取配置文件 通常项目会提供 docker-compose.yml 文件，如果找不到，可以使用 Apache APISIX 官方仓库的配置作为参考。

# 从官方示例获取 docker-compose 文件（假设 OpenClaw 兼容 APISIX 配置）
curl -o docker-compose.yml https://raw.githubusercontent.com/apache/apisix/master/docker/example/docker-compose.yml

步骤 2：编辑配置文件 修改 docker-compose.yml，确保以下服务存在：

• apisix/openclaw：网关本身。
• etcd：配置存储。
• apisix-dashboard：控制台（可选，但非常推荐用于图形化管理）。

OpenClaw 有专用的 Docker 镜像，请将 image: apache/apisix:latest 替换为 OpenClaw 的镜像地址，image: aicrayfish/openclaw:latest。

步骤 3：启动服务

# 在 docker-compose.yml 所在目录执行
docker-compose up -d

-d 参数表示在后台运行。

步骤 4：验证安装

# 检查容器是否运行
docker-compose ps
# 测试网关是否响应（默认端口 9080）
curl "http://127.0.0.1:9080"

如果返回 {"error_msg":"404 Route Not Found"}，说明网关进程运行正常，只是没有配置任何路由。

步骤 5：访问控制台（如果包含） docker-compose.yml 中包含了 apisix-dashboard，默认端口是 9000。

• 浏览器访问：http://你的服务器IP:9000
• 默认用户名/密码：admin / admin

---

第三部分：安装方式二：手动安装（适用于生产环境定制）

步骤 1：安装依赖

• Ubuntu/Debian:

  sudo apt update
  sudo apt install -y software-properties-common
  sudo add-apt-repository -y ppa:openresty/ppa
  sudo apt update
  sudo apt install -y openresty etcd curl

• CentOS/RHEL:

  sudo yum install -y yum-utils
  sudo yum-config-manager --add-repo https://openresty.org/package/centos/openresty.repo
  sudo yum install -y openresty etcd
  sudo systemctl start etcd
  sudo systemctl enable etcd

步骤 2：安装 OpenClaw/APISIX

• OpenClaw 提供 RPM/DEB 包：

  # CentOS
  sudo yum install /path/to/openclaw-xxx.rpm
  # Ubuntu
  sudo apt install /path/to/openclaw-xxx.deb

• 从源码安装（假设是APISIX衍生版）：

  # 1. 安装 LuaRocks（Lua包管理器）
  wget https://luarocks.org/releases/luarocks-3.9.1.tar.gz
  tar -xzf luarocks-3.9.1.tar.gz
  cd luarocks-3.9.1
  ./configure --with-lua=/usr/local/openresty/luajit \
              --lua-suffix=jit \
              --with-lua-include=/usr/local/openresty/luajit/include/luajit-2.1
  make && sudo make install
  # 2. 克隆 OpenClaw 代码库（请替换为实际仓库地址）
  git clone https://github.com/aicrayfish/openclaw.git
  cd openclaw
  # 3. 使用 LuaRocks 安装依赖和本体
  make deps
  sudo make install

步骤 3：配置

• 主配置文件通常位于 /usr/local/apisix/conf/config.yaml 或 /usr/local/openclaw/conf/config.yaml。
• 关键配置是 etcd 连接信息：

  deployment:
    role: traditional
    role_traditional:
      config_provider: etcd
    etcd:
      host:
        - "http://127.0.0.1:2379" # 确保与你的 etcd 地址一致
      prefix: "/apisix" # 配置在 etcd 中的前缀

步骤 4：启动服务

# 启动 APISIX/OpenClaw
sudo /usr/local/openresty/bin/openresty -p /usr/local/apisix/ -c /usr/local/apisix/conf/nginx.conf
# 或者使用提供的服务脚本
sudo systemctl start apisix

步骤 5：验证

curl "http://127.0.0.1:9080"

---

第四部分：基本使用测试

安装成功后,让我们创建一个简单的路由来验证网关功能。

通过 Admin API 创建路由（默认端口 9180，管理密钥在 conf/config.yaml 中）：

curl -i "http://127.0.0.1:9180/apisix/admin/routes/1" \
  -H "X-API-KEY: your-admin-key" \ # 默认是 `edd1c9f034335f136f87ad84b625c8f1`
  -X PUT -d '
{
  "uri": "/get",
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "httpbin.org:80": 1
    }
  }
}'

测试路由：

curl -i "http://127.0.0.1:9080/get"

如果成功,你会看到来自 httpbin.org 的响应。

第五部分：故障排查

1. 端口冲突：检查 9080， 9180， 9000， 2379 端口是否被占用。
2. etcd 连接失败：确保 etcd 已启动，config.yaml 中的连接信息正确。
3. 403 Forbidden：Admin API 请求头 X-API-KEY 不正确。
4. 查看日志：
   • Docker：docker-compose logs apisix
   • 手动安装：日志通常在 /usr/local/apisix/logs/ 目录下。
5. 最重要的：AI小龙虾 OpenClaw”有自己官方的安装文档或GitHub仓库，请务必以其官方文档为准，本教程是基于通用API网关（特别是Apache APISIX）的典型安装流程编写的。

希望这个详细的教程能帮助你成功安装和运行 OpenClaw 网关！

标签： 创建 工作目录