Sign inSign up

micrograils/workspace-hub

By micrograils

•Updated 20 days ago

Image
0

385

micrograils/workspace-hub repository overview

Docker Image Size Docker Pulls Platforms

⁠micrograils/workspace-hub

通用的「容器实例编排服务」——通过 REST API 批量创建/管理容器实例，每个用户一个容器 + 子域名。

一套代码，通过环境变量注入产品配置，即可复用于多产品线（VS Code、DeepSeek Harness 等）， 换产品线只需改一组 PRODUCT_ 环境变量，无需改动任何代码。

⁠组件一览

组件说明
FastAPIREST API 服务，管理实例生命周期（创建/列表/启停/删除）
Docker SDK动态创建/管理资源容器，携带 Traefik 标签自动发现路由
SQLite实例元数据 + 操作审计日志持久化
Traefik 集成可选，同步路由状态到实例列表（TRAEFIK_API_URL）
健康检查/health 端点 + 容器 HEALTHCHECK（curl）

⁠快速开始

⁠拉取镜像
docker pull micrograils/workspace-hub:latest
⁠启动服务（以 VS Code 产品线为例）
docker run -d --name workspace-hub \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v $(pwd)/data:/data \
  -p 127.0.0.1:26082:8000 \
  -e ADMIN_TOKEN=your-secret-token \
  -e PRODUCT_NAME=vscode \
  -e PRODUCT_DOMAIN=vscode.example.com \
  -e PRODUCT_IMAGE=linuxserver/code-server:latest \
  -e PRODUCT_INTERNAL_PORT=8443 \
  -e PRODUCT_MOUNT_PATH=/workspace \
  -e PRODUCT_DEFAULT_CPU=1 \
  -e PRODUCT_DEFAULT_MEMORY=1G \
  micrograils/workspace-hub:latest
⁠通过 API 管理实例
# 创建实例（自动创建容器 + 数据目录 + Traefik 路由）
curl -X POST http://127.0.0.1:26082/instances \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"username":"alice"}'

# 列出所有实例
curl http://127.0.0.1:26082/instances \
  -H "Authorization: Bearer your-secret-token"

# 启动 / 停止 / 重启
curl -X POST http://127.0.0.1:26082/instances/alice/start \
  -H "Authorization: Bearer your-secret-token"
curl -X POST http://127.0.0.1:26082/instances/alice/stop \
  -H "Authorization: Bearer your-secret-token"

# 删除实例（默认保留数据卷，purge=true 才删除数据目录）
curl -X DELETE "http://127.0.0.1:26082/instances/alice?purge=true" \
  -H "Authorization: Bearer your-secret-token"

创建后即可通过 http://alice.vscode.example.com 访问该用户的 VS Code 实例。

⁠环境变量

所有配置通过环境变量注入，按前缀归类。换产品线只需改 PRODUCT_ 一组变量。

⁠通用配置（所有产品线一致）
变量默认值说明
ADMIN_TOKEN（必填）API 认证凭证，校验 Authorization: Bearer <token>
ADMIN_PORT26082对外回环端口（nginx 反代目标）
DATA_ROOT/data宿主机数据卷根目录（每个用户一个子目录 data/<user>）
DATA_DB_PATH/data/workspace-hub.dbSQLite 数据库路径
TRAEFIK_API_URL（空）可选，Traefik API 地址，配置后启用路由状态同步
TRAEFIK_HOST（空）可选，访问 Traefik API 的 Host 头
NETWORK_NAMEdsh_network资源容器加入的 Docker 网络
CONTAINER_PREFIXdsh资源容器名前缀（如 dsh-alice）
⁠产品配置（每个产品线不同）
变量说明
PRODUCT_NAME产品标识（如 vscode、dsh），用于审计日志和目录隔离
PRODUCT_DOMAIN根域名（如 vscode.example.com），拼 <user>.<domain>
PRODUCT_IMAGE默认镜像（如 linuxserver/code-server:latest）
PRODUCT_INTERNAL_PORT容器内部端口（code-server 为 8443）
PRODUCT_MOUNT_PATH容器内数据卷挂载路径（code-server 为 /workspace）
PRODUCT_DEFAULT_CPU默认 CPU 配额（如 1）
PRODUCT_DEFAULT_MEMORY默认内存配额（如 1G）
⁠复用为其他产品线

仅需更换 PRODUCT_ 一组变量，例如 DeepSeek Harness：

  -e PRODUCT_NAME=dsh \
  -e PRODUCT_DOMAIN=dsh.example.com \
  -e PRODUCT_IMAGE=micrograils/deepseek-harness:latest \
  -e PRODUCT_INTERNAL_PORT=80 \
  -e PRODUCT_MOUNT_PATH=/home/dsh \
  -e PRODUCT_DEFAULT_CPU=2 \
  -e PRODUCT_DEFAULT_MEMORY=2G \

⁠Docker Compose（推荐）

services:
  workspace-hub:
    image: micrograils/workspace-hub:latest
    container_name: workspace-hub
    restart: unless-stopped
    ports:
      - "127.0.0.1:26082:8000"   # 仅回环，由外层 nginx 反代
    environment:
      - ADMIN_TOKEN=your-secret-token
      - PRODUCT_NAME=vscode
      - PRODUCT_DOMAIN=vscode.example.com
      - PRODUCT_IMAGE=linuxserver/code-server:latest
      - PRODUCT_INTERNAL_PORT=8443
      - PRODUCT_MOUNT_PATH=/workspace
      - PRODUCT_DEFAULT_CPU=1
      - PRODUCT_DEFAULT_MEMORY=1G
      # - TRAEFIK_API_URL=http://127.0.0.1:26081   # 可选，启用路由状态同步
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./data:/data

docker compose up -d
# 健康检查
curl http://127.0.0.1:26082/health

⁠REST API 一览

所有接口需 Authorization: Bearer <ADMIN_TOKEN>，可选 X-Actor 头标识操作者（记录到审计）。

方法路径说明
POST/instances创建实例（body: username/cpu/memory/image，后三者可选）
GET/instances列出所有实例（含实时状态与 Traefik 路由状态）
GET/instances/{username}单实例详情
DELETE/instances/{username}?purge=true删除实例（默认保留数据卷）
POST/instances/{username}/start启动实例
POST/instances/{username}/stop停止实例
POST/instances/{username}/restart重启实例
GET/audit检索操作审计（支持 actor/action/username/product/from/to/limit 筛选）
GET/health健康检查（无需认证）
GET/system/resources宿主机 CPU/内存/磁盘资源

⁠安全注意

⚠️ 安全警告：admin 挂载 docker.sock，拥有宿主机 Docker 的完全控制权。务必：

  • 设置强随机的 ADMIN_TOKEN，通过环境变量注入，不硬编码。
  • 仅在内网 / nginx 反代可达，不要直接暴露到公网。
  • 建议在 nginx 层加 TLS + Basic Auth 双重保护。

⁠镜像信息

  • 基础镜像: python:3.12-slim (Debian)
  • 核心组件: FastAPI + uvicorn + Docker SDK + SQLite
  • 健康检查: curl（容器内 HEALTHCHECK）
  • 运行用户: appuser（非 root，entrypoint 动态调整 docker 组权限后降权运行）
  • 数据存储: SQLite（DATA_DB_PATH），实例数据卷（DATA_ROOT/<user>）
  • 多架构: amd64 / arm64
  • 暴露端口: 8000（admin API）
  • 许可证: MIT

维护者文档（开发 / 构建 / 升级 / 维护）见 MAINTENANCE.md⁠。

项目介绍文章（设计思路与选型边界）见 articles/workspace-hub-通用容器实例编排服务.md⁠。

Tag summary

Content type

Image

Digest

sha256:36e7f32aa…

Size

61.5 MB

Last updated

20 days ago

docker pull micrograils/workspace-hub