使用 Docker 實際運行 OpenCode AI

Posted on by Rico

一個可重現、可控、可維運的 AI Coding 環境實作指南

AI Coding 工具（如 OpenCode AI）若直接安裝在開發者本機，雖然方便，但在團隊或企業環境中，往往會帶來：

  • 環境不一致
  • 憑證散落各處
  • 無法治理與稽核
  • 難以標準化導入

本文將示範 如何依照實務最佳做法，使用 Docker 建立一個可實際運行的 OpenCode AI 容器環境，讓 AI Coding 工具成為一個 可管理的工程元件。

一、整體設計目標

本實作的設計目標如下：

  • OpenCode AI 不直接安裝在主機
  • 使用 Docker 容器執行
  • 不將任何 API Token / 憑證寫入 Image
  • 使用非 root 使用者
  • 可重建、可版本控管
  • 適合未來擴充為團隊或企業標準

二、專案目錄結構

建議建立一個乾淨的目錄：

opencode-docker/
├── Dockerfile
├── build.sh
└── run.sh

三、Dockerfile（核心實作）

以下是一份 可直接使用的 Dockerfile，已包含實務上必要的修正與安全考量。

FROM ubuntu:latest

ENV DEBIAN_FRONTEND=noninteractive

# 安裝必要工具
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    ca-certificates \
    git \
    openssh-client \
    sudo \
 && rm -rf /var/lib/apt/lists/*

# 建立非 root 使用者
RUN useradd -m -s /bin/bash ubuntu \
 && echo "ubuntu ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/ubuntu \
 && chmod 0440 /etc/sudoers.d/ubuntu

USER ubuntu
WORKDIR /home/ubuntu

# 建立 SSH 目錄
RUN mkdir -p /home/ubuntu/.ssh \
 && touch /home/ubuntu/.ssh/known_hosts

# 預先加入 GitHub Host Key（避免互動式詢問）
RUN ssh-keyscan -T 5 github.com 2>/dev/null >> /home/ubuntu/.ssh/known_hosts || true

# 安裝 OpenCode AI（官方 binary）
RUN curl -fsSL https://opencode.ai/install | bash

✅ 重點說明

  • 沒有任何憑證寫進 image
  • OpenCode 以非 root 使用者執行
  • 適合企業資安稽核

四、Build Image

建立 build.sh：

#!/bin/bash
set -e

docker build -t opencode-ai:latest .

執行：

chmod +x build.sh
./build.sh

五、執行容器（關鍵實作）

OpenCode AI 需要使用者的認證資料，這些資料 必須存在主機上，再掛載進容器。

1️⃣ 主機端準備（只做一次）

登入一次 OpenCode（或依你實際使用方式）後，通常會產生：

~/.local/share/opencode/auth.json
~/.config/opencode/

2️⃣ run.sh（正式使用方式）

#!/bin/bash

docker run --rm -it \
  -v "$HOME/.local/share/opencode:/home/ubuntu/.local/share/opencode" \
  -v "$HOME/.config/opencode:/home/ubuntu/.config/opencode" \
  -v "$PWD:/workspace" \
  -w /workspace \
  opencode-ai:latest \
  opencode

執行：

chmod +x run.sh
./run.sh

六、實際使用情境

進入後，你會在容器內：

  • 使用 opencode 指令
  • 操作的是 目前專案目錄
  • 使用的是 你自己的憑證
  • 容器刪除後，不留任何狀態

這讓 OpenCode AI 的行為符合：

「工具可丟棄，資料留在主機」的雲原生設計原則

七、為什麼這種做法適合企業

✔ IT 管理面

  • 可統一 image 版本
  • 可做資安掃描
  • 可快速停用或更新

✔ 資安面

  • 憑證不進 image
  • 不以 root 執行
  • 降低供應鏈風險

✔ 工程面

  • 環境一致
  • 不污染主機
  • 新人上線成本低

八、常見延伸與下一步

這個架構可以自然延伸為：

  • 團隊共用的 OpenCode image
  • 內部 AI Coding 平台
  • CI Pipeline 中的 AI Review / Refactor 工具
  • 結合企業內部 RAG / 文件知識庫

結語

AI Coding 工具的價值不只在於「寫得快」，而在於：

是否能被安全、可控、長期地導入企業環境。

透過 Docker 容器化 OpenCode AI，我們可以把一個「個人工具」
轉變為 符合企業治理的工程能力。

這，才是 AI 在企業中真正可持續的導入方式。