Agent 容器安装手册¶

本文说明如何在 Docker 和 Kubernetes 中安装 obs-agent。如果您要安装到 Kubernetes，优先使用 Helm。

容器启动时会使用 BEAK_WS_URL、AGENT_ID 和 AGENT_API_KEY 从 Beak 获取运行配置，然后启动 agent。

持久化存储是运行前置条件。 /app 中保存运行中 session/task 的 JSONL 历史及相关数据，另外两个目录保存 profile 和 Owl 数据。Docker、Kubernetes YAML 和 Helm 部署都必须为 /app、/var/lib/obs-agent/profile-cache、/app/.owl 提供持久化存储。Owl 卷独立嵌套挂载到 /app/.owl。否则容器、Pod 重建或升级后，运行中的 session/task 可能因历史数据丢失而无法继续。

如果容器所在节点不能直连 Beak、LLM 或其他公网服务，请先阅读为 obs-agent 配置正向代理。

准备连接信息¶

从 Beak 控制台或安装页面复制这三个值。Docker 和 Kubernetes YAML 安装会使用全部三个值；从品牌 Helm 仓库安装时，Chart 已包含默认 Beak 地址，只会使用 AGENT_ID 和 AGENT_API_KEY，除非您需要覆盖 Beak 地址：

export BEAK_WS_URL='https://agent-api.guance.com'
export AGENT_ID='replace-with-agent-uuid'
export AGENT_API_KEY='replace-with-agent-api-key'

准备镜像地址：

export OBS_AGENT_IMAGE='pubrepo.guance.com/guance/obs-agent:v0.8.1'

用 Docker 安装¶

Docker 部署必须创建并重复挂载下面命令中的三个命名卷。升级或重启时应沿用相同的卷名；不要把这些挂载替换为容器临时目录。也可以使用由运维系统管理的 bind mount，但其生命周期必须独立于容器。

创建 env 文件：

cat > obs-agent.env <<EOF
BEAK_WS_URL=${BEAK_WS_URL}
AGENT_ID=${AGENT_ID}
AGENT_API_KEY=${AGENT_API_KEY}
EOF

启动容器：

docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --env-file ./obs-agent.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  -v obs-agent-owl:/app/.owl \
  "${OBS_AGENT_IMAGE}"

检查状态：

docker ps --filter name=obs-agent
docker logs -f obs-agent

日志中看到以下内容表示启动成功：

obs-agent profile request loaded
obs-agent websocket connected

升级镜像：

OBS_AGENT_IMAGE="${OBS_AGENT_IMAGE%:*}:v0.8.1"
docker pull "${OBS_AGENT_IMAGE}"
docker rm -f obs-agent
docker run -d \
  --name obs-agent \
  --restart unless-stopped \
  --env-file ./obs-agent.env \
  -v obs-agent-work:/app \
  -v obs-agent-profile-cache:/var/lib/obs-agent/profile-cache \
  -v obs-agent-owl:/app/.owl \
  "${OBS_AGENT_IMAGE}"

清理 Docker 安装：

下面的 docker volume rm 会永久删除 session/task 历史及相关数据。仅在确认不再需要恢复或继续任何任务时执行。

docker rm -f obs-agent
docker volume rm obs-agent-work obs-agent-profile-cache obs-agent-owl

用 Kubernetes YAML 安装¶

如果您不使用 Helm，可以直接使用发布到 OSS 的基础 manifest。

基础 manifest 会创建并挂载三个 PVC（20 GiB、5 GiB、5 GiB）。安装前，集群必须配置默认 StorageClass 以动态供应 PV，或预先准备可供这三个 PVC 绑定的 PV。PVC 未绑定时，Pod 会保持 Pending；不要改用 emptyDir 绕过该要求，否则 Pod 重建或升级会丢失运行中 session/task 的 JSONL 历史及相关数据。

下载 manifest：

curl -fsSL https://static.guance.com/obs-agent/obs-agent.yml -o obs-agent.yml

下载指定版本的 manifest：

curl -fsSL https://static.guance.com/obs-agent/obs-agent-v0.8.1.yml -o obs-agent.yml

创建 namespace：

kubectl create namespace obs-agent

manifest 使用环境变量保存 Beak 地址和 agent 凭据。确认本机已安装 envsubst，安装时只展开这三个变量，避免 URL 或凭据中的 /、& 等字符被替换命令解释：

envsubst '${BEAK_WS_URL} ${AGENT_ID} ${AGENT_API_KEY}' \
  < obs-agent.yml \
  | kubectl -n obs-agent apply -f -

obs-agent.yml 已经包含一个 Kubernetes Secret。上述 envsubst 命令会把当前环境中的凭据写入下面两个字段：

apiVersion: v1
kind: Secret
metadata:
  name: obs-agent-secret
type: Opaque
stringData:
  AGENT_API_KEY: "${AGENT_API_KEY}"
  AGENT_ID: "${AGENT_ID}"

检查状态：

kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy
kubectl -n obs-agent logs -f deploy/obs-agent

升级时重新下载新版 obs-agent.yml，保留当前 BEAK_WS_URL、AGENT_ID、AGENT_API_KEY，再执行：

envsubst '${BEAK_WS_URL} ${AGENT_ID} ${AGENT_API_KEY}' \
  < obs-agent.yml \
  | kubectl -n obs-agent apply -f -

升级时必须保留并复用原有 PVC。删除 PVC 或 namespace 可能连同底层 PV 数据一起删除，具体取决于 StorageClass 的回收策略。

清理 YAML 安装：

下面的命令会删除 manifest 创建的 PVC，底层 PV 数据是否保留取决于 StorageClass 的回收策略。仅在确认不再需要恢复或继续任何任务时执行。

kubectl -n obs-agent delete -f obs-agent.yml
kubectl delete namespace obs-agent

用 Kubernetes Helm 安装¶

Helm chart 默认创建并挂载三个 PVC（20 GiB、5 GiB、5 GiB）。安装前，集群必须配置默认 StorageClass 以动态供应 PV，或分别在 persistence.work.existingClaim、persistence.profileCache.existingClaim、persistence.owl.existingClaim 中指定三个已绑定的 PVC。不要禁用这些持久化项，否则 Pod 重建或升级会丢失运行中 session/task 的 JSONL 历史及相关数据。

设置 Helm 仓库地址，然后添加仓库：

Helm 仓库地址与容器镜像仓库地址不同。不要把后续 image.repository 使用的镜像路径作为 helm repo add 的仓库地址。

export OBS_AGENT_HELM_REPO_URL='https://pubrepo.guance.com/chartrepo/obs-agent'
helm repo add obs-agent "${OBS_AGENT_HELM_REPO_URL}"
helm repo update obs-agent
helm search repo obs-agent

创建 namespace：

kubectl create namespace obs-agent

创建 agent secret：

kubectl -n obs-agent create secret generic obs-agent-secret \
  --from-literal=AGENT_ID="${AGENT_ID}" \
  --from-literal=AGENT_API_KEY="${AGENT_API_KEY}"

品牌 Helm Chart 已包含当前品牌的默认 Beak 地址，正常安装时不需要手动设置 config.BEAK_WS_URL。

安装：

helm upgrade --install obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --set image.repository=pubrepo.guance.com/guance/obs-agent \
  --set image.tag=v0.8.1 \
  --set secret.existingSecret=obs-agent-secret

只有使用自定义 Beak 地址、安装未包含品牌默认地址的旧版 Chart，或直接从仓库源码 docs/examples/helm/obs-agent 安装时，才需要在安装命令中追加 --set-string config.BEAK_WS_URL="${BEAK_WS_URL}"。

检查状态：

kubectl -n obs-agent get pods
kubectl -n obs-agent get deploy -l app.kubernetes.io/instance=obs-agent
kubectl -n obs-agent logs -f deploy/obs-agent

如果 Deployment 名不是 obs-agent，用上面的 kubectl get deploy 输出中的实际名称查看日志。

升级：

helm upgrade obs-agent obs-agent/obs-agent \
  --namespace obs-agent \
  --reuse-values \
  --set image.tag=v0.8.1

如果旧 release 的 values 中已经保存了错误或未解析的 Beak 地址，--reuse-values 会继续复用该值。首次升级到修复后的 Chart 时，请额外传入 --set-string config.BEAK_WS_URL="${BEAK_WS_URL}" 修正它；后续升级可以继续复用。

清理 Helm 安装：

helm uninstall 会删除 chart 创建的 PVC，kubectl delete namespace 也会删除该 namespace 中的 PVC。底层 PV 数据是否保留取决于 StorageClass 的回收策略；仅在确认不再需要恢复或继续任何任务时执行。

helm uninstall obs-agent -n obs-agent
kubectl delete namespace obs-agent

查看可用环境变量¶

所有安装方式都需要 AGENT_ID 和 AGENT_API_KEY。Docker 和 Kubernetes YAML 安装还需要 BEAK_WS_URL；品牌 Helm Chart 已提供默认值，仅在自定义地址或兼容旧 Chart 时需要覆盖。下面的其他变量用于排查问题或覆盖默认配置；没有明确需求时不用设置。

注意事项¶

• Docker 和 Helm 不能复用同一个 AGENT_ID 同时在线。每个运行实例需要独立 agent。
• 仅替换镜像升级的旧部署如果仍把 Owl 卷挂载到 /var/lib/obs-agent/work/.owl，entrypoint 会在未显式设置 OWL_DIR 时检测并继续使用该目录；更新到新 Compose、Kubernetes 或 Helm 模板后则使用 /app/.owl。迁移期间不要同时挂载两个 Owl 卷。
• obs-agent.yml 会创建独立 ServiceAccount，并关闭 Kubernetes service account token 自动挂载。
• 容器内不会运行宿主机安装脚本，也不依赖 systemd。
• 容器化部署不启用本地自更新；升级通过替换镜像 tag 或 digest 完成。
• 生产环境建议使用镜像 digest 固定版本。