1 非商用声明

该文档提供的内容为参考实践，仅供用户参考使用，用户可参考实践文档构建自己的软件，按需进行安全、可靠性加固，但不建议直接将相关Demo或镜像文件集成到商用产品中。

2 方案介绍

2.1 背景介绍

随着大语言模型技术的普及，基于Agent（智能体）的 AI 辅助编程已成为研发人员不可或缺的日常基础设施。然而，在企业或特定研发环境中普及 AI 开发时，全托管的云端工具往往伴随着代码资产泄露风险与高昂的订阅成本。因此，基于本地模型或企业内部算力进行离线私有化部署，成为了保障核心数据安全、实现定制化开发的必然选择。

作为开源 AI 编程框架的代表，OpenCode 凭借对多模型后端的灵活支持与高扩展性的插件生态，成为了打通大模型能力与私有开发环境的核心桥梁。在完全隔离的离线环境下，能够快速部署一套稳定可靠、开箱即用且深度集成本地模型的 OpenCode 服务底座，不仅能确保全流程代码数据不出网，更能显著降低企业接入 AI 的门槛，对普及安全合规的 AI 辅助开发具有至关重要的落地价值。

2.2 方案架构

本实践所使用的特性架构如图所示：

图1 AI编程一体机（OpenCode）部署架构示意图

本实践围绕 OpenCode 的私有化部署，提供一套基于openFuyao的部署方案，集成以下特性：

1、集成 E2B 沙箱插件：可在独立的沙箱环境中执行指定命令，保护Agent环境。

2、集成OpenViking记忆管理功能：可将上下文记忆存储到OpenViking记忆仓库中，让上下文可检索，可复用。

3、集成SkillHub的skill管理功能：可将内部发布的skill快速部署到到本地使用，或者将本地开发的skill快速上传。

4、集成Envoy Gateway ：屏蔽了底层复杂配置，以 Kubernetes 原生方式为企业级微服务提供高性能、高可靠的统一流量入口与安全屏障。

5、Ceph 持久化：选用Ceph RBD 作为持久化存储，保存 OpenCode 工作目录数据，Pod 重建后关键数据不丢失。

6、宿主机OS安全加固：提供环境检查脚本，对宿主机安全配置进行检查，给出加固建议。

7、Helm Chart 一键部署：提供标准化的 Helm Chart，将 OpenCode 服务、Envoy Gateway 路由、Ceph 持久化等资源统一管理，一条命令即可拉起全栈服务。

本方案的目标是降低私有化 OpenCode 部署的技术门槛，形成高可用，易部署，可复用、可扩展的私有化部署样例。

2.3 典型配置

针对不同的业务场景，给出不同的推荐配置，供参考：

表1 AI编程一体机典配方案-鲲鹏服务器-硬件规格

表2 AI编程一体机典配方案-昇腾服务器

表3 组件资源配置表

3 部署指南

3.1 软件版本

本实践中所用到的软件版本如下：

3.2 部署流程

方案整体部署流程如下所示：

1、部署OpenFuyao平台。

2、下载/构建部署所需的镜像和软件等（离线部署可选）。

3、在昇腾服务器上部署模型服务。

4、部署记忆服务，为Agent提供上下文和记忆管理功能（可选）。

5、部署私有SkillHub，提供Skill管理服务（可选）。

6、部署E2B沙箱服务，为Agent提供安全运行环境（可选）。

7、部署网关服务，提供统一访问接口。

8、OS安全检查。

9、部署OpenCode应用实例。

其中，步骤1~8可分别参考以下参考实践进行部署，本实践重点介绍OpenCode实例部署：

openFuyao部署：  https://www.hikunpeng.com/zh/developer/techArticles/20260701-8

模型服务部署： https://www.hiascend.com/zh/developer/techArticles/20260630-1  

公用服务部署（记忆服务，SkillHub服务，E2B沙箱服务，网关服务）+OS安全检查： https://www.hiascend.com/zh/developer/techArticles/20260630-5

3.3 OpenCode实例部署

本方案部署OpenCode实例分为以下几个步骤：

1、将基于Dockerfile构建OpenCode镜像上传至镜像仓。

2、将提供的HelmChart文件上传至openFuayo本地仓库。

3、在openFuyao的管理界面，修改values.yaml参数，创建应用实例，或者进行管理。

其中values.yaml参数的修改和介绍，见参数配置指南章节，或者参考代码仓中的README.md。

注意！Helm Charts中的values配置文件包含用户名和密码信息，若在生产环境中使用，建议采用加密或外部密钥管理方式保护敏感信息，避免泄露。

步骤1：构建OpenCode镜像并上传至镜像仓。

下载并进入Dockerfile文件所在路径（https://gitcode.com/Ascend/ascend-deployer/blob/appliance_deployer/kadt/opencode/build-images/full）。如果环境中没有docker运行时，可替换成nerdctl等其它运行时命令。

下载代码仓：

# 下载指定分支代码仓
git clone -b appliance_deployer --single-branch --depth 1 https://gitcode.com/Ascend/ascend-deployer.git
# 进入dockerfile路径
cd kadt/opencode/build-images/full

基础镜像使用openEuler-24.03-LTS-SP3，如果docker pull拉取基础镜像存在问题，可以下载镜像压缩包，然后导入镜像：

# 拉取openEuler镜像
docker pull openeuler/openeuler:24.03-lts-sp3
# 修改tag 并 push 到私有镜像仓库
docker tag openeuler/openeuler:24.03-lts-sp3 deploy.bocloud.k8s:40443/openeuler:24.03-lts-sp3
docker push deploy.bocloud.k8s:40443/openeuler:24.03-lts-sp3

镜像默认构建命令如下（为了安全性，默认不会进行换源和关闭SSL）：

docker build -t deploy.bocloud.k8s:40443/opencode-e2b-full:<tag> .

支持通过 --build-arg 传入参数，例如使用换源和关闭SSL加速构建，注意需要用户自行保证安全性：

docker build --build-arg mirrors_nossl=True-t deploy.bocloud.k8s:40443/opencode-e2b-full:<tag> .

如需在构建时配置网络代理，参考如下命令进行构建：

# 有代理构建
docker build \
  --build-arg HTTP_PROXY=http://proxy:port \
  --build-arg HTTPS_PROXY=http://proxy:port \
  --build-arg NO_PROXY=127.0.0.1,localhost \
  -t deploy.bocloud.k8s:40443/opencode-e2b-full:<tag> .

制作好镜像后，修改镜像tag并上传至镜像仓

docker push deploy.bocloud.k8s:40443/opencode-e2b-full:<tag>

步骤2：将HelmChart文件上传openFuayo本地仓库。

HelmChart下载地址（ https://gitcode.com/Ascend/ascend-deployer/tree/appliance_deployer/kadt/opencode/charts/opencode-e2b-helm ），下载后，需要手动制作为.tar.gz的压缩包。

上传前，建议先同步一次本地仓，防止在向本地仓上传时报错。操作方式为，进入openFuyao管理界面，从“应用市场”中进入“仓库配置”界面，找到local仓库，执行“同步仓库”，同步成功后会有成功提示，可参考图示操作。

图1 openFuyao同步local仓然后上传HelmChart压缩包，注意需要将HelmChart文件压缩为.tar.gz或者.tgz格式，然后从“应用市场”的“仓库配置”中，进入“包管理”，然后点击“添加包”，会弹出上传界面，然后如图点击“上传文件”后指定压缩包文件即可。

图2 进入openFuyao的包管理界面，点击“添加包”

图3 使用openFuyao上传包

步骤3：在openFuyao的管理界面，定制化修改参数，进行应用的创建与发放。

从“应用市场”进入应用列表，找到之前上传的opencode应用，然后点击应用，进入应用创建界面，修改参数后进行创建。具体参数配置方式，在参数配置指南章节详细介绍。如果想快速拉起实例，可以关闭其它特性，只进行4.1章节的基础配置。

图4 找到上传的OpenCode应用

图5 修改相关配置参数后，一键部署。

成功部署的应用，可以在应用管理中找到，支持在WEBUI上进行升级、回退、卸载等操作。

图6 在应用管理中，找到部署的应用，进行管理。

4 参数配置指南

4.1 OpenCode基础配置（快速拉起）

本章节介绍OpenCode实例，在values.yaml中的基础参数配置，例如使用的命名空间，镜像，实例后缀，登陆用户名密码等。

如果需要进行最小配置进行快速服务拉起，可先将如下特性使能配置为false（E2B+SkillHub+OpenViking），然后完成本小节的参数配置，即可快速拉起OpenCode实例。

1、opencode.e2b.enabled

2、opencode.e2b.sandboxEnabled

3、opencode.skillhub.enabled

4、opencode.openviking.enabled

本小节的配置可分为3部分：基础配置，模型配置，网关配置。

1、基础配置

每个不同实例，都需要配置不同的实例后缀，可以使用不同用户名来区分不同使用者（Alice，Bob等）。

登陆凭据注入方式为环境变量 OPENCODE_SERVER_USERNAME / OPENCODE_SERVER_PASSWORD，同时用于 Health Probe 的 HTTP Basic Auth 鉴权。

表1 基础信息配置

每个实例分配的系统资源按照如下配置（存储资源还有ceph，在后续配置章节介绍）：

表2 主容器资源相关参数

2、模型配置

OpenCode使用时，需要提供LLM模型服务，values中配置LLM服务的参数示例如下：

  llm:
    providers:
      local_model_provider:
        name: local-model-service
        npm: "@ai-sdk/openai-compatible"
        options:
          baseURL: "http://YOUR_LLM_HOST:8000/v1"
          apiKey: "YOUR_LLM_API_KEY"
        models:
          deepseek_v4_flash:
            name: dsv4

3、网关配置

OpenCode实例对外提供服务的路由方式，推荐使用Gateway方式：

表4 支持的路由方式

在values.yaml中对应的配置参数如下：

表5 网络相关参数配置

两种路由方案都需要有listener，在服务器上创建listener的参考命令如下：

kubectl patch gateway -n xxxx cluster-gateway --type='json' -p='[
  {
    "op": "add",
    "path": "/spec/listeners/-",
    "value": {
      "name": "opencode-service-v3",
      "port": xxxx,
      "protocol": "HTTP",
      "allowedRoutes": {
        "kinds": [
          {"kind": "HTTPRoute"}
        ],
        "namespaces": {
          "from": "All"
        }
      }
    }
  }
]'

方式一：hostname 模式（按域名绑定，所有实例共享1个listener）

Gateway 根据请求的域名（Host 头）来分发流量。给 OpenCode 配一个域名，例如按照实例后缀进行渲染（比如 bob.opencode.local），Gateway 看到请求 Host 是这个域名，就知道要转发给 OpenCode。这样同一个端口上可以挂多个服务，靠域名区分。

Gateway Listener: 18799
  ├── HTTPRoute hostname=alice.opencode.local       → Service-alice
  └── HTTPRoute hostname=bob.opencode.local         → Service-bob

适用场景： 有域名，多个服务共享一个 Gateway 端口，共享1个Listener，通过不同域名（实例后缀）来区分。

配置方式： bindMode配置为hostname（例如bob），baseDomain配置为基域（例如opencode.local），OpenCode 会自动生成子域名{hostPrefix}.{baseDomain}，例如bob.opencode.local。

使用域名访问时，需进行DNS配置，对于Windows PC，修改C:\Windows\System32\drivers\etc\hosts文件，在文件末尾添加'IP 域名'后保存即可使用域名:端口访问Openclaw实例，如添加如下配置后可通过http://bob.opencode.local:18799地址访问。

{Gateway IP} bob.opencode.local

方式二：sectionName 模式（按端口名绑定）

创建每个实例前，提前在Gateway 上创建新的listener，让每个OpenCode实例独占一个listener。

连接通路： Envoy Gateway (gatewayIP:listenerPort) ──→ HTTPRoute (sectionName 匹配 listener 名称) ──→ Service (opencode-service-clusterip, ClusterIP) ──→ containerPort ──→ Pod 

适用场景： 没有域名，直接用 IP + 端口访问。每个OpenCode实例需要独占一个Listener。

配置方式： 需要先保证 Gateway 上有未被占用的 Listener，然后在 values 里把 bindMode 配置为 sectionName，listenerName 配置为 Listener 的名字。

4.2 安全沙箱 （E2B）

E2B服务 可以提供独立的沙箱执行环境，当 OpenCode 需要执行 shell 命令或 Python 脚本时，可以选择在 E2B 沙箱中执行，而不是在本地容器中执行，实现安全隔离。

使用该特性前，需要环境中已经提供E2B沙箱公共服务（参考部署流程章节）和OpenCode实例中安装配套的E2B插件（实例部署章节提供的Dockerfile中会自动安装）。如果期望其它Agent使能E2B特性，需要自行开发配套插件（可参考当前OpenCode已有插件）。

本章节介绍配置使能E2B特性，在使用HelmChart的values.yaml中，配置以下E2B相关的参数，即可在拉起的OpenCode实例中使能沙箱特性：

表1 E2B沙箱相关参数

完成相关配置并拉起OpenCode服务后，可以local-exec提示词，指定运行在E2B环境中。例如“使用local-exec执行uname -a”，可以观察到返回的E2B信息，与在本地执行的返回值不同。

图1 在沙箱执行命令

图2 在本地执行命令

4.3 安全配置

OpenCode自身并未进行沙箱隔离，如果需要环境隔离，请将OpenCode启动在沙箱或者容器中。

OpenCode具有工具执行能力，如果想对命令执行加以控制，可以单独配置工具权限，具有以下三种等级（官方参考文档：https://opencode.ai/docs/permissions）：

1、"allow" — 无需审批直接运行

2、"ask" — 提示审批

3、"deny" — 阻止该操作

可以在opencode.jsonc文件中（全局生效：~/.config/opencode/opencode.jsonc），例如参考如下配置，高危操作（rm）需要用户同意，修改文件时，除了项目空间外的内容，也需要同意：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "rm *": "ask",
    },
    "edit": {
      "*": "ask",
      "~/oc_space": "allow"
    }
  }
}

4.4 技能管理（SkillHub）

SkillHub是一个可本地部署的技能市场，提供私有部署的技能发布、下载和管理能力，可通过下载SkillHub的CLI工具来接入SkillHub服务。

本章节介绍如何在HelmChart部署的OpenCode实例中使用SkillHub，前置要求已经完成SkillHub服务的部署，并创建个人token。

创建个人Token的方式为，登陆拉起的SkillHub服务的Web界面，然后从账号页进入控制台，然后选择创建API Token：

图1 登陆后首页

图2 创建API Token

在HelmChart的values.yaml中，配置以下SkillHub相关的参数，即可在拉起的OpenCode实例中使能SkillHub技能管理特性：

本方案主要实现为，将SkillHub的CLI构建到镜像中，在通过HelmChart拉起实例时，只需要配置登陆信息，即可使用SkillHub。

使能SkillHub后，可让OpenCode通过“skillhub --help”指令自行查询使用方式，也可以手动使用SkillHub-CLI的内置命令。

图3 让OpenCode查询SkillHub-CLI的使用方式

也可手动执行相关操作，SillHub-CLI的使用命令参考如下，或者可查阅官方文档（https://iflytek.github.io/skillhub/guide/skill-publish.html）：

1、登陆（若没有在values.yaml配置登陆token，可手动创建token后，在OpenCode实例中完成登陆）：

# 登录，输入创建好的api token和SkillHub地址
skillhub login --token sk_xxxx --registry http://xxxx

登陆后，可以whoami查看当前登陆的账号信息

# 查看当前登陆的账号信息
skillhub whoami

# 预期有如下格式回显
Registry: xxxx
Handle: xxxx
Name: xxxx

2、其它常用操作参考如下：

# 上传技能，不指定namespace则默认上传到global空间
skillhub publish ./{your_skill}  --namespace {your_namespace}

# 使用关键字，搜索技能库中可用技能
skillhub search {keyword}

# 下载安装skill到指定Agent，默认使用global空间，agent参数填写所使用的Agent名称，例如opencode
skillhub install    {skill_name} --agent opencode
# 回显显示具体的下载路径
Installed {your_workspace}/{skill_name} -> /root/.opencode/skills/{skill_name} (opencode)

# 删除已安装技能
skillhub remove {skill_name}

4.5 记忆管理（OpenViking）

OpenViking 是一个开源的、专为 AI Agent 设计的上下文数据库，将所有上下文（Memory、Resource、Skill）统一抽象为目录结构，支持语义检索和渐进式内容加载。

需要在集群中， 提前部署好可用的OpenViking服务，以及在OpenCode实例的namespace中配置配置好OpenViking服务的ROOT API KEY（或者采用创建个人key，则不需要此配置，具体可参考README和values注释）。

OpenViking Secret 创建方式如下：

kubectl create secret generic openviking-secrets -n 'your-opencode-namespace'  --from-literal=OPENVIKING_ROOT_API_KEY='your-root-api-key'

说明： Secret 必须在 helm install / helm upgrade 之前存在于命名空间中，否则 Pod 启动失败。Secret 更新后需重启 Pod 才能生效。

本方案通过将OpenViking插件构建到镜像中，只需要在values.yaml中配置以下参数，然后使用HelmChart拉起OpenCode实例，即可使能OpenViking特性：

插件会通过 OpenCode tool hook 暴露这些工具，例如对OpenCode输入“记住一个magic number=2341”，让其自动触发记忆工具，或者显式指定调用“使用memcommit提交记忆”，支持的工具有：

1、memsearch：语义检索 memories/resources/skills

2、memread：读取具体 viking:// URI

3、membrowse：浏览 OpenViking 文件系统

4、memcommit：提交当前 session 并触发记忆提取

5、memgrep：精确文本或模式搜索

6、memadd：添加远端 URL 或本地文件资源

详细含命令含义和用法可参考官方代码仓文档：https://github.com/volcengine/OpenViking/blob/main/examples/opencode-plugin/INSTALL-ZH.md

4.6 基于Ceph的持久化存储

本方案支持接入Ceph块存储的PVC持久化存储，前置条件为在集群中提前部署好Ceph服务。

使能接入Ceph的持久化存储特性，在values.yaml中配置以下相关参数：

使能该特性后，对应的自动化操作为：

1. 自动创建 PVC（命名为opencode-pvc{instanceSuffix}），使用指定 StorageClass。
2. PVC 挂载到 Pod 的 /root（mountPath 可配置），首次挂载时 init 容器将镜像 /root 内容同步到 PVC。
3. 后续 Pod 重启时检测到 PVC 已有数据，跳过同步以保留现有内容，防止镜像原有内容覆盖存储内容。