OpenCodeTeam

Go 编排服务，为 OpenCode 提供多租户团队协作方案。本项目能够为每个团队成员分配独立的 Docker 容器作为开发工作区，提供统一的 JWT 认证、反向代理、容器生命周期管理、LLM 服务端点管理以及多维度使用审计和统计。

---

核心功能

1. 多租户容器编排与生命周期管理

• 按需拉起与冷启动：基于 Docker SDK 动态为每个用户冷启动或停止工作区容器。当用户访问其专属工作区路径时，若容器未运行，系统将自动秒级拉起该用户的容器。
• 独立的存储与配置挂载：
  • 工作空间：将宿主机的 ~/.opencode-team/users/<userID>/workspace 挂载到容器的 /workspace（读写）。
  • 用户数据：将宿主机的 ~/.opencode-team/users/<userID>/data 挂载到容器的 /home/opencode（读写），用于持久化 .config、.cache 等工具链配置。
  • 通用技能库：将宿主机的 ~/.opencode-team/skills 只读挂载到容器的 /home/opencode/.config/opencode/skills。
• 安全隔离运行：容器内的进程以宿主机当前运行 manager 进程的 UID 与 GID 权限运行，彻底避免了 root 权限污染文件，并规避了 Git 仓库的 safe.directory 权限冲突。
• 资源上限控制：每个工作区容器被严格限制为最大 2 GB 内存 以及 2 个 CPU 核心。

2. 高效反向代理与连接劫持

• 统一网关代理：集成 HTTP 反向代理和 WebSocket 双向转发（hijack），完美支撑 OpenCode 在线 IDE 的复杂通信需求。
• 多级凭证解析：路由分发自动从 HTTP Header (Authorization: Bearer)、Query 参数 (?token=) 或 Cookie 中提取 Token 进行鉴权。
• 智能前端绝对路径转发：通过解析 Referer 标头和在 Cookie 中设置 proxy_target，解决了管理员代开/访问普通用户 IDE 时，因前端 History API 重写根目录绝对路径资源导致的反代冲突。

3. 多租户 LLM 提供商配置 (Provider Config)

• 全局提供商池管理：管理员可以统一增删改查全局大模型提供商（如 OpenAI、DeepSeek、OpenRouter 等），并支持将其中某个设为默认（Default）。
• 灵活绑定与自定义：系统支持将用户与全局大模型提供商绑定；同时，也支持为特定用户配置专属的自定义 API Key、大模型名、Endpoint URL 以及 Context Limit（上下文限制，默认 128k）。
• 配置自动渲染与幂等更新：系统会将用户的 LLM 信息自动转换为 OpenCode 所需的 opencode.jsonc 格式。对全局绑定的用户强制重写，对自定义用户则具有幂等性保护（如用户在本地做了改动则不予覆盖）。

4. 多维度管理员使用统计 (Usage Statistics)

• 动态审计引擎：从每位用户本地的 SQLite 数据库（opencode.db）中动态读取和聚合实时使用状态，管理员可一键异步刷新，数据结果配有 TTL 缓存（默认 5 分钟）。
• 多维聚合指标：
  • 项目数 (Project Count)：智能合并去重 SQLite 数据库记录、宿主机 workspace 实际物理目录、用户会话目录。
  • 会话与消息：统计全部会话数、分析单条消息 JSON 并提取 role == "user" 的用户发言次数。
  • Token 消耗：自动计算 tokens_input + tokens_output。
  • 技能调用统计 (Skill Count)：扫描宿主机共享的 SKILL.md，基于文本指纹特征（Signature）在日志与推理段中匹配，并辅助检测 read/view_file 路径。
  • MCP 工具调用次数：判定并解析非内置的第三方 Model Context Protocol (MCP) 扩展工具调用。
• 活跃度模型 (Active Score)：基于以下公式计算并展示 Top 10 活跃用户和最受欢迎的技能/MCP：

$$ \text{Active Score} = \text{ProjectCount} \times 100 + \text{SessionCount} \times 10 + \text{UserMessageCount} \times 1 + \text{TokenCount} \times 0.001 $$

5. 管理员无容器模式与安全防护

• 容器隔离：系统彻底禁止为 admin 管理员账号启动任何 Docker 容器，保障后台资源纯净与宿主机安全。
• 管理界面隐藏：将 admin 从普通用户列表中彻底过滤与隐藏，且拒绝任何人通过 API 对 admin 发起容器生命周期控制。

6. 控制台全面中文化 (I18n)

• 控制台（包含登录页面、用户配置管理、LLM 提供商管理、审计统计仪表盘等）全面支持中文，提升本地化运维与管理体验。

7. 定制化离线工作区镜像 (Docker)

• 提供包含全套开发工具链的自定义工作区镜像：内置 Git、Node.js 20、Python 3.13、uv、bun、ripgrep，以及用于生成代码索引的本地 MCP 服务 codegraph。

---

目录结构

• cmd/manager/main.go - 程序主入口，使用 Cobra 框架解析命令行 Flag 与环境变量，执行数据库初始化和种子化配置，并拉起 Gin Web 服务。
• internal/config/config.go - 配置中心，负责从系统环境变量与命令行参数中加载和展开路径（自动识别 ~ 符号）。
• internal/auth/auth.go - 鉴权模块，负责 JWT Token 的签名生成和验证鉴权。
• internal/model/ - 数据实体：
  • user.go - User 实体，包括密码 Bcrypt 哈希、大模型提供商绑定关系等。
  • provider.go - 全局大模型提供商 ProviderConfig 实体。
• internal/docker/manager.go - Docker 容器生命周期管理器，封装 Docker SDK 以提供容器创建、启动、冷启动、状态巡检、停止和删除功能，以及自动生成工作区大模型配置文件。
• internal/audit/audit.go - 审计与指标统计引擎，负责免打扰式、以只读模式动态解析用户容器内 OpenCode SQLite 数据库，并聚合各项使用指标与 Skill / MCP 排行榜。
• internal/handler/ - 路由控制器层：
  • router.go - 定义全局路由规则、JWT 鉴权拦截、以及反向代理劫持的核心网关逻辑。
  • user.go - 多租户用户管理的 RESTful API 处理器。
  • provider.go - 大模型提供商管理的 RESTful API 处理器。
  • stats.go - 仪表盘统计数据接口，配有 RWMutex 读写锁的高性能缓存层。
  • proxy.go - HTTP 反代与 WebSocket Hijack 双通道实现。
• internal/logger/logger.go - 日志引擎，提供结构化的标准输出（Console）与本地滚动日志双输出支持。
• internal/web/ - 前端静态资产，以 HTML/CSS/JS (Tailwind CSS) 实现，使用 Go 1.16+ 的 go:embed 技术完全打包进 manager 二进制程序内，实现单文件便捷交付。
• deploy/ - 部署配置文件：
  • Dockerfile.manager - Manager 服务端的轻量化构建文件。
  • Dockerfile.opencode-custom - 工作区容器的定制化镜像构建脚本。
  • docker-compose.yml - 多容器编排部署（包含 Caddy 反向代理网关）。
  • Caddyfile - Caddy 路由及静态文件解析规则。
• build_start-custom.sh - 自动化构建与启动脚本，编译最新的自定义镜像并使用本地 Go 环境或二进制启动 manager 服务。
• start-custom.sh - 离线快速启动脚本，免去了镜像与源码编译，直接启动本地已有的二进制产物。

---

环境准备 (宿主机)

# 1. 配置本地域名解析
echo '127.0.0.1 admin.opencode-team' | sudo tee -a /etc/hosts
echo '127.0.0.1 skills.opencode-team' | sudo tee -a /etc/hosts

# 2. 预先创建数据卷与技能挂载目录
mkdir -p ~/.opencode-team/skills ~/.opencode-team/users

---

启动与部署

1. 本地直接开发启动（宿主机需具备 Go 环境与 Docker socket）

go run cmd/manager/main.go --port 8080 --jwt-secret "your-jwt-secret" --db-path "~/.opencode-team/manager.db"

Note

首次启动时，系统会自动在 SQLite 中初始化管理员账号，默认凭证为：用户名 admin / 密码 admin123。您可以在启动前通过注入环境变量（如 DEFAULT_API_KEY 等）自定义管理员初始模型属性。

2. 构建自定义工作区镜像并启动（集成完整工具链）

./build_start-custom.sh

3. 离线直接启动（依赖 ./deploy/manager 二进制，跳过编译）

./start-custom.sh

4. 生产环境 Docker Compose 一键启动

cd deploy
docker-compose up -d

---

单元测试

所有测试均默认采用 :memory: 内存型 SQLite 数据库，不需要提前安装或依赖运行中的 Docker daemon。您可以安全地在 CI 或无容器环境执行：

go test -v ./...

---

配置参数说明

Cobra 与 Config 包支持通过 命令行 Flag 与 环境变量 双向读取配置参数，命令行 Flag 的优先级最高：

命令行 Flag	环境变量	默认值	作用说明
-p, --port	PORT	8080	Manager 服务监听的 HTTP 端口
--jwt-secret	JWT_SECRET	default-secret-key-change-me	JWT 鉴权与签名的 Secret 密钥
--db-path	DB_PATH	~/.opencode-team/manager.db	SQLite 数据库路径 (自动展开 ~)
--docker-network	DOCKER_NETWORK	opencode-team	租户容器加入的桥接 Docker 网络名
--base-data-dir	BASE_DATA_DIR	~/.opencode-team	本地数据存储与挂载的基础工作目录
--host-data-dir	HOST_DATA_DIR	同 BASE_DATA_DIR	宿主机实际物理卷路径 (用于 DIND 容器内挂载映射)
--opencode-image	OPENCODE_IMAGE	ghcr.io/anomalyco/opencode:latest	默认拉起的用户开发工作区 Docker 镜像
--log-path	LOG_PATH	~/.opencode-team/logs/manager.log	系统日志保存路径
-v, --version	-	-	打印程序当前版本号、Git 提交短 Hash 以及构建时间