# 05-08-openclaw K3s 实验部署（不推荐生产）

> **实验性文档**：尝试将 OpenClaw Gateway 直接以 Deployment/Service/Ingress 的形式运行在 K3s 中。  
> 官方推荐的方式仍是 **Docker / Docker Compose 部署**（参考 `05-07-openclaw应用部署.md` 与官方文档），本篇仅供有 K8s 经验的读者实验与参考。


## TL;DR

- **自动化验收**：`./ansible/bin/verify.sh run 05-08`
- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
- **成功判据**：达到本文「预期」且 playbook 断言通过
- **排障**：见本文「排障」

## 前置条件

- 已完成基础集群安装：`01-01`、`01-02`
- Traefik 入口已可用（参考 `03-01-k3s-traefik-dashboard.md`）
- 能访问 OpenClaw 官方仓库并在某个节点上构建 Docker 镜像
- 熟悉基本的 Deployment/Service/Ingress 概念

## 重要警告（务必阅读）

- OpenClaw 官方目前**没有提供稳定维护的 K8s/Helm Chart**，其推荐部署方式是 Docker/Compose。  
- 本文示例基于官方 Dockerfile 改写为 Deployment，仅覆盖「能跑起来网关 UI」这一最小目标，**不承诺与未来版本兼容**。  
- 如需长期使用，请优先采用 `05-07-openclaw应用部署.md` 中的「x86 Docker + K3s 反向代理」方案。

---

## 1. 构建并推送 OpenClaw 镜像

在一台可访问官方源码的 x86 节点上（可以是 K3s 节点，也可以是单独构建机）：

```bash
# 克隆官方仓库（路径示例）
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 构建镜像（示例 tag，按需替换 registry）
docker build -t registry.local/openclaw:local -f Dockerfile .

# 推送到你的镜像仓库（或使用本地 registry）
docker push registry.local/openclaw:local
```

> 提示：如果你没有私有镜像仓库，也可以先在某个 K3s 节点上本地构建镜像，并通过 `containerd` 导入方式让节点识别本地镜像，这部分不在本文展开。

---

## 2. 在 K3s 中部署 OpenClaw Gateway

下面是一个**高度简化的实验性 Deployment/Service/Ingress 示例**，其目标只是让你能在集群内/通过 Traefik 访问 OpenClaw Gateway 控制界面。

**唯一真源**：[`ansible/files/05-08/openclaw-k3s-experimental.yaml`](../ansible/files/05-08/openclaw-k3s-experimental.yaml)（实验用；替换镜像与域名）。

> 说明：示例使用 `emptyDir`；若要持久化请改为 PVC/hostPath。

应用部署：

```bash
kubectl apply -f ansible/files/05-08/openclaw-k3s-experimental.yaml
```

---

## 3. 验证部署

### 3.1 集群内资源状态

```bash
kubectl -n openclaw get pod,svc,ing -o wide
```

预期：

- `openclaw-gateway` Pod 处于 `Running` 状态
- Service 与 Ingress 正常创建，无错误事件

### 3.2 通过 Traefik 访问控制界面

在能解析 `openclaw-k3s.example.com` 到集群入口 IP 的客户端上：

```bash
curl -I --max-time 5 http://openclaw-k3s.example.com/
```

预期：

- 返回 `200` 或重定向到 OpenClaw 控制 UI
- 在浏览器中打开 `http://openclaw-k3s.example.com/`，可以看到 OpenClaw 的 Web 控制界面（可能需要按官方文档完成 token 配对与设备授权）

---

## 4. 已知限制与注意事项

- **升级/版本变更风险**：官方 Dockerfile 或启动参数一旦更新，你的 Deployment 可能需要手动跟进调整。  
- **配置/工作区持久化**：示例中使用 `emptyDir`，容器重启后配置和 workspace 会丢失；若要长期使用，必须改成 PVC 或 hostPath，并自行规划备份。  
- **安全与资源配额**：未对 CPU/内存/网络策略做细致约束，不适合作为严格生产环境配置。

如需更安全、维护成本更低的方案，请优先参考：

- `05-07-openclaw应用部署.md`（x86 Docker + K3s 反向代理）
- 官方文档 `https://docs.openclaw.ai/zh-CN/install/docker`

---

## 下一步

- 若你验证了本实验方案在自己的环境中稳定可用，建议在本篇文档中补充验证备注（注明镜像版本、节点架构与日期）。  
- 返回 `00-00-构建总览.md`，按导航继续阅读其它运维/排障文档。

## 排障

- **先看 playbook 输出**：失败时先定位是 deploy/wait/http_check 哪一步。
- **集群侧总览**：`kubectl get nodes -o wide`、`kubectl -n kube-system get pods -o wide`。
- **事件与日志**：`kubectl -n <ns> describe ...`、`kubectl -n <ns> logs ... --tail=200`。