企业级部署 —— 集中配置、CI/CD 集成、监控告警与团队部署

简介

在前面的系列文章中，我们逐步掌握了 OpenCode 的安装认证、Provider 选择、命令运行、TUI 交互、Session 管理、Agent 双模式、PR 审查、并行工作、提示词工程和自定义配置等核心功能。当个人开发者已经能熟练运用 OpenCode 提升效率时，一个新的问题随之而来：如何在一个团队甚至整个企业中规模化部署 OpenCode？

企业级部署不仅仅是"给每个人装一个 opencode"那么简单。它涉及配置的一致性管理、API Key 的安全分发、与现有 CI/CD 流水线的集成、运行时监控和告警、团队规则的统一下发，以及合规审计等一系列工程化问题。

本文将系统讲解 OpenCode 的企业级部署方案：

集中配置管理：统一规则、统一模型、统一策略的分发机制
CI/CD 集成：在 GitHub Actions、GitLab CI、Jenkins 中嵌入 OpenCode Agent
监控告警：Token 用量、成本追踪、异常行为检测
团队部署：多角色权限、工作空间隔离、最佳实践

一、集中配置管理

1.1 为什么需要集中配置？

在没有集中配置管理的情况下，团队成员各自维护 .opencode/settings.json，必然导致：

配置漂移：不同人使用不同的模型、不同的规则、不同的工具权限
安全漏洞：有人可能关闭了确认提示，导致 Agent 可以随意执行危险命令
维护困难：新增一条全局规则需要逐个仓库手动修改
合规风险：审计时无法证明所有 Agent 实例都遵循了企业安全策略

集中配置管理就是要解决这些问题，确保企业内所有 OpenCode 实例运行在统一、可控、可审计的状态下。

1.2 配置分发策略

OpenCode 的三层配置架构天然支持企业级集中管理。推荐的企业配置方案如下：

text

┌──────────────────────────────────────────────────────────────┐
│  企业级配置中心 (Git 仓库 / Config Server)                      │
│                                                              │
│  ├── baseline/                                                │
│  │   ├── settings.json        ← 全局基线配置                   │
│  │   ├── rules/                                              │
│  │   │   ├── security.md      ← 安全规范（强制）               │
│  │   │   ├── coding-style.md  ← 编码规范（强制）               │
│  │   │   └── code-review.md   ← 代码审查规范（强制）           │
│  │   └── context/                                            │
│  │       └── enterprise.yaml  ← 企业信息、API 端点列表         │
│  ├── teams/                                                   │
│  │   ├── frontend/settings.json  ← 前端团队覆盖                │
│  │   ├── backend/settings.json   ← 后端团队覆盖                │
│  │   └── infra/settings.json     ← 基础设施团队覆盖            │
│  └── projects/                                                │
│      └── ...                   ← 项目级特化配置                 │
└──────────────────────────────────────────────────────────────┘

基线配置示例：

json

// baseline/settings.json
{
  "$schema": "https://opencode.ai/schema/settings.json",
  "provider": {
    "default": "corporate-anthropic",
    "models": {
      "corporate-anthropic": {
        "model": "claude-sonnet-4-20250514",
        "base_url": "https://api-proxy.company.internal/v1"
      }
    }
  },
  "agent": {
    "max_iterations": 25,
    "plan_review_required": true,
    "auto_approve": [],
    "always_allow": ["read", "glob", "grep"]
  },
  "tools": {
    "restricted": {
      "terminal": {
        "require_confirmation": true,
        "blocked_commands": ["rm -rf", "chmod 777", "mkfs", "dd"]
      },
      "write": {
        "require_confirmation": true,
        "allowed_paths": ["src/**", "test/**", "docs/**"]
      }
    }
  },
  "rules": {
    "auto_load": true,
    "paths": [
      "rules/security.md",
      "rules/coding-style.md",
      "rules/code-review.md"
    ]
  },
  "audit": {
    "log_level": "verbose",
    "log_path": "~/.opencode/logs/",
    "include_tool_calls": true,
    "include_token_usage": true
  }
}

1.3 自动化配置同步

配置同步是企业部署的核心环节。推荐以下两种方案：

方案 A：Git Submodule + 初始化脚本

bash

#!/bin/bash
# scripts/init-opencode.sh - 项目初始化时自动拉取企业配置

set -euo pipefail

CONFIG_REPO="git@github.company.com:engineering/opencode-config.git"
CONFIG_DIR=".opencode/enterprise"

# 如果企业配置目录不存在，则克隆
if [ ! -d "$CONFIG_DIR" ]; then
  echo "📦 正在拉取企业 OpenCode 配置..."
  git clone --depth 1 "$CONFIG_REPO" "$CONFIG_DIR"
fi

# 更新到最新版本
cd "$CONFIG_DIR" && git pull --ff-only

# 验证配置
echo "🔍 验证配置完整性..."
if opencode config validate --config "$CONFIG_DIR/baseline/settings.json"; then
  echo "✅ 企业配置验证通过"
else
  echo "❌ 企业配置验证失败，请检查"
  exit 1
fi

# 创建软链接或合并配置
ln -sf "$CONFIG_DIR/baseline/settings.json" .opencode/settings.json
echo "✅ 企业配置已应用到当前项目"

将此脚本加入项目的 Makefile 或 setup 流程：

makefile

.PHONY: setup
setup:
	@echo "🚀 初始化项目开发环境..."
	bash scripts/init-opencode.sh
	npm install  # 或其他包管理
	@echo "✅ 环境初始化完成"

方案 B：配置 Server + 定时拉取

bash

#!/bin/bash
# scripts/sync-opencode-config.sh - 定时从配置中心同步

CONFIG_SERVER="https://config.company.internal/opencode"
TEAM="backend"
VERSION="${1:-latest}"

echo "📡 从配置中心同步 OpenCode 配置..."
echo "   团队: $TEAM"
echo "   版本: $VERSION"

# 拉取配置包
curl -sSf "$CONFIG_SERVER/config/$TEAM/$VERSION.tar.gz" \
  -o /tmp/opencode-config.tar.gz

# 解压到企业配置目录
mkdir -p .opencode/enterprise
tar -xzf /tmp/opencode-config.tar.gz -C .opencode/enterprise

# 验证并应用
opencode config validate --config .opencode/enterprise/settings.json \
  && echo "✅ 配置已更新" \
  || echo "❌ 配置无效，保留旧版本"

rm -f /tmp/opencode-config.tar.gz

配合 cron 实现定时同步：

bash

# crontab - 每天凌晨2点同步配置
0 2 * * * cd /path/to/project && bash scripts/sync-opencode-config.sh >> /var/log/opencode-sync.log 2>&1

1.4 环境变量统一管理

企业的 API Key 和敏感配置不能硬编码到 settings.json 中，应通过环境变量管理：

bash

# .env.enterprise - 企业环境模板（不包含真实 Key）
OPENCODE_PROVIDER_API_KEY=${OPENCODE_PROVIDER_API_KEY}
OPENCODE_PROVIDER_BASE_URL=https://api-proxy.company.internal/v1
OPENCODE_AUDIT_LOG_DIR=/var/log/opencode/
OPENCODE_TELEMETRY_ENDPOINT=https://telemetry.company.internal/collect

# 在 settings.json 中引用环境变量
{
  "provider": {
    "models": {
      "corporate-anthropic": {
        "model": "claude-sonnet-4-20250514",
        "api_key_env": "OPENCODE_PROVIDER_API_KEY",
        "base_url_env": "OPENCODE_PROVIDER_BASE_URL"
      }
    }
  },
  "telemetry": {
    "endpoint_env": "OPENCODE_TELEMETRY_ENDPOINT"
  }
}

在企业环境中，通过 HashiCorp Vault 或 AWS Secrets Manager 注入这些环境变量：

bash

# Vault 注入示例
vault kv get -field=api_key secret/opencode/anthropic > /tmp/.opencode_key
export OPENCODE_PROVIDER_API_KEY=$(cat /tmp/.opencode_key)
rm /tmp/.opencode_key

二、CI/CD 集成

2.1 为什么要在 CI/CD 中集成 OpenCode？

将 OpenCode 集成到 CI/CD 流水线可以实现：

自动 PR 审查：每次提交自动触发 Agent 进行代码审查
自动修复：对简单的 lint 错误、格式问题自动修复并提交
文档生成：根据代码变更自动生成更新日志和变更说明
安全扫描：Agent 辅助进行安全代码审查

2.2 GitHub Actions 集成

自动 PR 审查 Workflow：

yaml

# .github/workflows/opencode-review.yml
name: OpenCode PR Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup OpenCode
        uses: opencode-ai/setup-opencode@v1
        with:
          version: "latest"
          provider: "anthropic"

      - name: Run PR Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_TITLE: ${{ github.event.pull_request.title }}
        run: |
          # 获取 PR 变更
          git fetch origin main
          git diff origin/main --name-only > changed_files.txt

          # 使用 OpenCode Agent 审查
          opencode run \
            --mode agent \
            --context changed_files.txt \
            --context .opencode/rules/code-review.md \
            --prompt "请审查 PR #${PR_NUMBER}: '${PR_TITLE}' 的代码变更。
              关注点：
              1. 潜在的安全漏洞
              2. 是否符合编码规范（参考 .opencode/rules/coding-style.md）
              3. 是否有更好的实现方式
              4. 是否需要补充测试用例

              请将审查结果以 Markdown 格式输出，包含：
              - 总体评价
              - 逐项发现的问题（按严重程度排序）
              - 改进建议（附带代码示例）
              - 是否建议合并" \
            > review_output.md

          # 将审查结果作为 PR 评论发布
          gh pr comment "$PR_NUMBER" \
            --body "$(cat review_output.md)" \
            || echo "⚠️ 无法发布评论，请检查权限"

      - name: Upload Review Artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: review-report
          path: review_output.md

自动修复 Workflow：

yaml

# .github/workflows/opencode-autofix.yml
name: OpenCode Auto Fix

on:
  push:
    branches: [main, develop]

permissions:
  contents: write
  pull-requests: write

jobs:
  autofix:
    runs-on: ubuntu-latest
    if: github.actor != 'opencode-bot[bot]'
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Setup OpenCode
        uses: opencode-ai/setup-opencode@v1

      - name: Run Auto Fix
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          opencode run \
            --mode agent \
            --prompt "检查项目中的以下问题并自动修复：
              1. 未使用的 import/变量
              2. 拼写错误的注释
              3. 缺失的文档字符串
              4. 代码格式不一致的地方

              请逐一修复并在完成后提交。"

      - name: Commit and Push
        run: |
          git config user.name "opencode-bot"
          git config user.email "opencode-bot@company.internal"
          git add -A
          if git diff --cached --quiet; then
            echo "✅ 没有需要修复的问题"
          else
            git commit -m "chore(opencode): 自动修复代码质量问题"
            git push
          fi

2.3 GitLab CI 集成

yaml

# .gitlab-ci.yml
stages:
  - test
  - review
  - deploy

opencode-review:
  stage: review
  image: ubuntu:24.04
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
  variables:
    ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
  script:
    - apt-get update && apt-get install -y curl git
    - curl -fsSL https://opencode.ai/install | bash
    - opencode run \
        --mode agent \
        --context .opencode/rules/code-review.md \
        --prompt "审查本次 MR 的变更，输出 Markdown 格式的审查报告" \
      > review.md
    - |
      # 发布 MR 评论
      curl --header "PRIVATE-TOKEN: $GITLAB_API_TOKEN" \
        --data-urlencode "body=$(cat review.md)" \
        "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
  artifacts:
    reports:
      markdown:
        - review.md

2.4 Jenkins Pipeline 集成

groovy

// Jenkinsfile
pipeline {
    agent any

    environment {
        ANTHROPIC_API_KEY = credentials('anthropic-api-key')
        OPENCODE_VERSION = 'latest'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('OpenCode Review') {
            steps {
                sh '''
                    # 安装 OpenCode
                    curl -fsSL https://opencode.ai/install | bash

                    # 执行代码审查
                    opencode run \
                        --mode agent \
                        --context .opencode/rules/security.md \
                        --prompt "进行安全代码审查" \
                        > review-result.md
                '''
            }
            post {
                always {
                    archiveArtifacts artifacts: 'review-result.md'
                    // 可以通过邮件或 Slack 发送审查报告
                }
            }
        }
    }
}

三、监控告警

3.1 Token 用量与成本追踪

企业部署必须对 Token 消耗和成本有清晰的可见性。

用量日志采集：

bash

#!/bin/bash
# scripts/collect-opencode-metrics.sh - 采集用量指标

LOG_DIR="${OPENCODE_AUDIT_LOG_DIR:-~/.opencode/logs}"
OUTPUT_DIR="/var/log/opencode/metrics"
DATE=$(date +%Y-%m-%d)

mkdir -p "$OUTPUT_DIR"

# 提取今天的 Token 用量统计
echo "📊 正在采集 OpenCode 用量数据..."

# 解析审计日志中的 token 信息
grep -h "\"token_usage\"" "$LOG_DIR"/*.log 2>/dev/null \
  | jq -r '.token_usage | "\(.prompt_tokens),\(.completion_tokens),\(.total_tokens)"' \
  | awk -F',' '{
      prompt+=$1; completion+=$2; total+=$3; count++
    }
    END {
      if(count>0) {
        printf "{\"date\":\"%s\",\"sessions\":%d,\"prompt_tokens\":%d,\"completion_tokens\":%d,\"total_tokens\":%d,\"avg_tokens_per_session\":%d}\n",
          "'"$DATE"'", count, prompt, completion, total, total/count
      }
    }' > "$OUTPUT_DIR/daily-$DATE.json"

# 成本估算（根据不同模型定价）
MODEL_PRICES='{
  "claude-sonnet-4-20250514": {"input": 3.0, "output": 15.0},
  "claude-opus-4-20250514": {"input": 15.0, "output": 75.0},
  "gpt-4o": {"input": 2.5, "output": 10.0}
}'

# 生成日报
echo "✅ 用量数据已保存到 $OUTPUT_DIR/daily-$DATE.json"

成本仪表盘数据源：

json

// 示例输出
{
  "date": "2025-05-22",
  "team": "backend",
  "sessions": 147,
  "prompt_tokens": 2847563,
  "completion_tokens": 1923847,
  "total_tokens": 4771410,
  "avg_tokens_per_session": 32459,
  "estimated_cost_usd": 42.73,
  "top_models": [
    {"model": "claude-sonnet-4-20250514", "sessions": 128, "cost": 35.21},
    {"model": "gpt-4o", "sessions": 19, "cost": 7.52}
  ],
  "top_users": [
    {"user": "zhang-san", "sessions": 43, "cost": 12.85},
    {"user": "li-si", "sessions": 31, "cost": 9.47}
  ]
}

3.2 Prometheus 指标暴露

OpenCode 可以通过自定义脚本暴露 Prometheus 格式的指标：

python

#!/usr/bin/env python3
# exporters/opencode_metrics.py

import os
import json
import glob
import time
from http.server import HTTPServer, BaseHTTPRequestHandler

METRICS_DIR = "/var/log/opencode/metrics"

def collect_metrics():
    """从日志目录聚合指标"""
    total_sessions = 0
    total_tokens = 0
    total_cost = 0.0
    errors = 0

    for f in glob.glob(f"{METRICS_DIR}/daily-*.json"):
        try:
            with open(f) as fh:
                data = json.load(fh)
                total_sessions += data.get("sessions", 0)
                total_tokens += data.get("total_tokens", 0)
                total_cost += data.get("estimated_cost_usd", 0)
        except (json.JSONDecodeError, KeyError):
            errors += 1

    return {
        "opencode_sessions_total": total_sessions,
        "opencode_tokens_total": total_tokens,
        "opencode_cost_usd_total": round(total_cost, 2),
        "opencode_metric_parse_errors": errors,
        "opencode_last_scrape_timestamp": int(time.time())
    }

class MetricsHandler(BaseHTTPRequestHandler):
    def do_GET(self):
        if self.path == "/metrics":
            metrics = collect_metrics()
            output = ""
            for name, value in metrics.items():
                if isinstance(value, float):
                    output += f"# TYPE {name} gauge\n{name} {value:.2f}\n"
                else:
                    output += f"# TYPE {name} counter\n{name} {value}\n"
            self.send_response(200)
            self.send_header("Content-Type", "text/plain")
            self.end_headers()
            self.wfile.write(output.encode())
        else:
            self.send_response(404)

if __name__ == "__main__":
    server = HTTPServer(("0.0.0.0", 9199), MetricsHandler)
    print("📡 OpenCode metrics exporter listening on :9199")
    server.serve_forever()

Prometheus 配置：

yaml

# prometheus.yml
scrape_configs:
  - job_name: "opencode"
    static_configs:
      - targets: ["opencode-metrics:9199"]
    scrape_interval: 5m

3.3 告警规则

yaml

# alertmanager/opencode-alerts.yml
groups:
  - name: opencode-alerts
    rules:
      # Token 用量激增告警
      - alert: OpenCodeTokenUsageSpike
        expr: rate(opencode_tokens_total[1h]) > 100000
        for: 15m
        labels:
          severity: warning
        annotations:
          summary: "OpenCode Token 用量异常增长"
          description: "过去1小时 Token 用量超过阈值，可能存在 Agent 循环或异常调用"

      # 成本超预算告警
      - alert: OpenCodeDailyCostExceeded
        expr: increase(opencode_cost_usd_total[1d]) > 100
        for: 0m
        labels:
          severity: critical
        annotations:
          summary: "OpenCode 日成本超过预算"
          description: "当日累计成本已超过 $100，请检查是否有异常使用"

      # 会话异常频繁告警
      - alert: OpenCodeHighSessionRate
        expr: rate(opencode_sessions_total[30m]) > 50
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "OpenCode 会话创建频率过高"
          description: "每分钟新会话超过 50 个，可能存在自动化脚本滥用"

      # 指标采集失败告警
      - alert: OpenCodeExporterDown
        expr: up{job="opencode"} == 0
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "OpenCode 指标采集器离线"
          description: "OpenCode 指标采集器已离线超过 5 分钟"

3.4 安全审计

企业部署需要对 Agent 行为进行完整审计：

bash

# 启用完整审计日志
{
  "audit": {
    "log_level": "verbose",
    "log_path": "/var/log/opencode/audit/",
    "include_tool_calls": true,
    "include_token_usage": true,
    "include_prompt_snippets": false,  // 不记录 prompt 内容（隐私保护）
    "rotate_max_size_mb": 100,
    "rotate_max_files": 30,
    "format": "jsonl"  // JSON Lines 格式，便于后续分析
  }
}

审计日志分析脚本：

bash

#!/bin/bash
# scripts/audit-analysis.sh - 分析审计日志

AUDIT_DIR="/var/log/opencode/audit"
DATE_RANGE="${1:-7}"  # 默认分析过去7天

echo "🔍 OpenCode 审计分析报告"
echo "   时间范围: 过去 ${DATE_RANGE} 天"
echo ""

# 统计工具调用频率
echo "📊 工具调用 TOP 10:"
find "$AUDIT_DIR" -name "*.log" -mtime -"$DATE_RANGE" \
  | xargs grep -h '"tool_name"' \
  | jq -r '.tool_name' \
  | sort | uniq -c | sort -rn | head -10
echo ""

# 统计被阻止的操作
echo "🚫 被阻止的操作:"
find "$AUDIT_DIR" -name "*.log" -mtime -"$DATE_RANGE" \
  | xargs grep -h '"blocked":true' \
  | jq -r '"[\(.timestamp)] \(.user) 尝试执行: \(.command)"' \
  | head -20
echo ""

# 统计异常 session（超长或超高 token 消耗）
echo "⚠️  异常 Session（Token 消耗 > 500K）:"
find "$AUDIT_DIR" -name "*.log" -mtime -"$DATE_RANGE" \
  | xargs grep -h '"session_end"' \
  | jq -r 'select(.token_usage.total_tokens > 500000) |
    "[\(.timestamp)] Session \(.session_id): \(.token_usage.total_tokens) tokens"' \
  | head -20

四、团队部署

4.1 多角色权限模型

企业内不同角色对 OpenCode 的权限需求不同：

text

┌─────────────┬──────────────────┬──────────────────┬──────────────────┐
│ 角色        │ 模型权限          │ 工具权限          │ 审批权限        │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ 初级开发者   │ Sonnet 及以下     │ Read + Write     │ 需 Senior 审批   │
│             │ 确认：全部开启    │ (限定路径)       │ Plan 必须审查    │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ 高级开发者   │ 全部模型          │ Read + Write     │ 自主审批         │
│             │ 确认：写操作开启  │ + Terminal 受限  │ Plan 自主执行    │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ Tech Lead   │ 全部模型          │ 全部工具         │ 自主审批         │
│             │ 成本预警开启      │ (含网络请求)     │ 可修改团队规则   │
├─────────────┼──────────────────┼──────────────────┼──────────────────┤
│ 运维工程师   │ Opus + Sonnet    │ Terminal (sudo)  │ 自主审批         │
│             │ Infra 模型        │ Infra 工具集     │ 生产环境双人审批 │
└─────────────┴──────────────────┴──────────────────┴──────────────────┘

基于角色的配置文件示例：

json

// 初级开发者配置
{
  "provider": {
    "default": "corporate-anthropic",
    "allowed_models": ["claude-sonnet-4-20250514", "gpt-4o-mini"]
  },
  "agent": {
    "max_iterations": 15,
    "plan_review_required": true,
    "require_approval_for": ["write", "terminal", "edit"]
  },
  "tools": {
    "restricted": {
      "terminal": {
        "require_confirmation": true,
        "allowed_commands": ["ls", "cat", "grep", "find", "git"],
        "blocked_commands": ["sudo", "rm", "chmod", "curl", "wget"]
      },
      "write": {
        "require_confirmation": true,
        "allowed_paths": ["src/**", "test/**"],
        "blocked_paths": ["**/config/**", "**/secrets/**", "**/*.key"]
      }
    }
  },
  "cost_limit": {
    "daily_max_usd": 5,
    "session_max_usd": 1,
    "alert_on_percent": 80
  }
}

json

// Tech Lead 配置
{
  "provider": {
    "default": "corporate-anthropic",
    "allowed_models": [
      "claude-opus-4-20250514",
      "claude-sonnet-4-20250514",
      "gpt-4o",
      "deepseek-v3"
    ]
  },
  "agent": {
    "max_iterations": 50,
    "plan_review_required": false,
    "auto_approve": ["read", "glob", "grep", "edit"]
  },
  "tools": {
    "allowed": ["read", "write", "terminal", "edit", "web_fetch"]
  },
  "cost_limit": {
    "daily_max_usd": 50,
    "session_max_usd": 10,
    "alert_on_percent": 80
  }
}

4.2 工作空间隔离

在多团队、多项目环境中，工作空间隔离是必要的：

bash

# 项目级工作空间结构
/workspace/
├── project-a/
│   ├── .opencode/
│   │   ├── settings.json       ← 项目 A 的配置
│   │   ├── rules/              ← 项目 A 的规则
│   │   └── sessions/           ← 项目 A 的会话历史
│   ├── src/
│   └── test/
│
├── project-b/
│   ├── .opencode/
│   │   ├── settings.json       ← 项目 B 的配置（不同模型/规则）
│   │   ├── rules/
│   │   └── sessions/
│   └── src/
│
└── shared/
    ├── enterprise-config/       ← 企业级基线配置
    │   ├── baseline/
    │   └── teams/
    └── audit-logs/             ← 集中审计日志

通过 OPENCODE_WORKSPACE 环境变量控制工作空间：

bash

# 为不同项目设置不同的工作空间
export OPENCODE_WORKSPACE=/workspace/project-a/.opencode
opencode run --prompt "修复用户认证模块的 bug"

# 或者通过 wrapper 脚本
#!/bin/bash
# scripts/opencode-wrapper.sh
PROJECT_NAME=$(basename "$(pwd)")
export OPENCODE_WORKSPACE="/workspace/${PROJECT_NAME}/.opencode"
export OPENCODE_CONFIG_FILE="${OPENCODE_WORKSPACE}/settings.json"

# 确保工作空间目录存在
mkdir -p "$OPENCODE_WORKSPACE"/{sessions,rules,logs}

# 应用企业基线配置
if [ -f "/workspace/shared/enterprise-config/baseline/settings.json" ]; then
  # 合并企业基线配置
  opencode config merge \
    --base "/workspace/shared/enterprise-config/baseline/settings.json" \
    --override "$OPENCODE_CONFIG_FILE"
fi

exec opencode "$@"

4.3 团队部署 Checklist

阶段	检查项	状态
准备	企业 API Key 已配置到 Vault/Secrets Manager	☐
	基线配置文件已提交到企业配置仓库	☐
	安全规则文件已完成法务/安全团队审核	☐
	监控和告警基础设施已就绪	☐
部署	所有项目已接入集中配置同步	☐
	CI/CD 流水线已集成 OpenCode 审查	☐
	团队成员已完成工具培训	☐
	角色权限配置文件已下发	☐
运营	每日 Token 用量报告自动生成	☐
	成本超预算告警已验证有效	☐
	审计日志定期归档（30天滚动）	☐
	月度配置回顾和规则更新机制	☐

4.4 部署脚本模板

bash

#!/bin/bash
# scripts/deploy-opencode-team.sh - 团队一键部署脚本
# 用法: bash deploy-opencode-team.sh <team-name>

set -euo pipefail

TEAM_NAME="${1:?请指定团队名称}"
CONFIG_REPO="git@github.company.com:engineering/opencode-config.git"

echo "🚀 开始部署 OpenCode 到团队: $TEAM_NAME"
echo ""

# 1. 验证环境
echo "📋 验证环境..."
command -v opencode >/dev/null 2>&1 || { echo "❌ OpenCode 未安装"; exit 1; }
command -v jq >/dev/null 2>&1 || { echo "❌ jq 未安装"; exit 1; }

# 2. 拉取配置
echo "📦 拉取团队配置..."
TEMP_DIR=$(mktemp -d)
git clone --depth 1 "$CONFIG_REPO" "$TEMP_DIR/config"
echo "   ✅ 配置已拉取"

# 3. 验证基线配置
echo "🔍 验证基线配置..."
opencode config validate --config "$TEMP_DIR/config/baseline/settings.json"
echo "   ✅ 基线配置验证通过"

# 4. 应用团队覆盖
echo "🔧 应用团队覆盖配置..."
if [ -f "$TEMP_DIR/config/teams/$TEAM_NAME/settings.json" ]; then
  echo "   找到团队专属配置: $TEAM_NAME"
  cp "$TEMP_DIR/config/teams/$TEAM_NAME/settings.json" \
    .opencode/settings.json
else
  echo "   未找到团队专属配置，使用基线配置"
  cp "$TEMP_DIR/config/baseline/settings.json" \
    .opencode/settings.json
fi

# 5. 部署规则文件
echo "📜 部署规则文件..."
mkdir -p .opencode/rules
cp "$TEMP_DIR/config/baseline/rules/"*.md .opencode/rules/ 2>/dev/null || true

# 6. 验证最终配置
echo "✅ 验证最终配置..."
opencode config validate --config .opencode/settings.json

# 7. 清理
rm -rf "$TEMP_DIR"

echo ""
echo "🎉 OpenCode 部署完成!"
echo ""
echo "📊 部署信息:"
echo "   团队: $TEAM_NAME"
echo "   配置: .opencode/settings.json"
echo "   规则: .opencode/rules/"
echo "   工作空间: $(pwd)/.opencode/"
echo ""
echo "💡 下一步:"
echo "   1. 运行 'opencode config show' 查看生效配置"
echo "   2. 运行 'opencode run --prompt \"hello\"' 快速验证"
echo "   3. 将 .opencode/ 加入版本控制（排除 logs/ 和 sessions/）"

总结

本文系统讲解了 OpenCode 的企业级部署方案：

集中配置管理：三层配置架构（全局基线 → 团队覆盖 → 项目特化），通过 Git 仓库或配置 Server 实现统一分发，配合环境变量管理敏感信息
CI/CD 集成：在 GitHub Actions、GitLab CI、Jenkins 中嵌入 OpenCode Agent，实现自动 PR 审查、自动修复、文档生成等
监控告警：Token 用量追踪、成本仪表盘、Prometheus 指标暴露、分级告警规则、完整安全审计
团队部署：多角色权限模型（初级开发 → Tech Lead → 运维）、工作空间隔离、一键部署脚本、部署 Checklist

企业级部署的核心原则是统一配置、分级权限、全程可审计、成本可控。

下篇预告

下一篇我们将进入 OpenCode 的故障排查与调优 主题——当 Agent 不按预期工作时如何快速定位问题，包括 PATH 环境变量问题、TUI 界面卡死处理、优雅退出策略、常见错误码解析、性能调优技巧等实战内容。无论你是日常使用还是企业运维，这篇都是必备参考。敬请期待！