跳至主要内容

Workspace Manager

概覽​

Workspace Manager 是 Aileron 的核心服務，負責管理開發工作區的完整生命週期，包括建立、設定、啟動、停止和刪除。

核心功能​

工作區管理​

  • CRUD：建立、讀取、更新、刪除工作區
  • 容器管理：Docker / Kubernetes 容器生命週期控制
  • Marketplace 支援：管理 agent 套件與 provider 設定
  • 網路配置：防火牆規則和端口映射管理

團隊協作​

  • 多用戶支援：工作區成員管理
  • 權限控制：基於角色的存取控制（RBAC）
  • 團隊管理：團隊建立和成員邀請

自動化任務​

  • Cron 排程：Cron 表達式支援的定時任務
  • AI 整合：可驅動 agent workflow 的自動化任務，目前以 Claude Code 最完整
  • 執行監控：任務執行狀態和結果追蹤

技術架構​

元件技術
Web 框架FastAPI
ORMSQLAlchemy
資料庫PostgreSQL
快取 / 佇列Redis
背景任務Celery
容器管理Docker / Kubernetes
認證Keycloak JWT

目錄結構​

workspace-manager/
├── app/
│   ├── celery/            # Celery 背景任務設定
│   ├── config/            # 配置模組
│   ├── core/              # 核心功能
│   ├── db/                # 資料庫連線與遷移
│   ├── jinja_templates/   # Jinja2 模板
│   ├── middleware/        # 中間件
│   ├── models/            # SQLAlchemy 資料模型
│   ├── modules/           # 功能模組
│   ├── routers/           # API 路由
│   ├── services/          # 業務邏輯層
│   ├── tasks.py           # Celery 任務定義
│   ├── translations/      # 多語系資源
│   └── utils/             # 工具函數
├── scripts/               # 部署腳本
├── tests/                 # 測試
├── pyproject.toml
└── Dockerfile

環境變數​

基礎設定​

變數名預設值說明
DATABASE_URL—PostgreSQL 連線 URL
REDIS_URL—Redis 連線 URL
SECRET_KEY—JWT 簽名密鑰
DOCKER_HOSTunix:///var/run/docker.sockDocker 主機
DEBUGfalse除錯模式

Keycloak 認證設定（可選）​

變數名預設值說明
ENABLE_AUTHfalse啟用 Keycloak OAuth2/OIDC
KEYCLOAK_SERVER_URL—Keycloak 伺服器 URL（含 realm）
KEYCLOAK_REALMaileronKeycloak realm 名稱
KEYCLOAK_CLIENT_ID—OAuth2 客戶端 ID
KEYCLOAK_CLIENT_SECRET—OAuth2 客戶端密鑰
JWT_ALGORITHMRS256JWT 驗證算法
JWT_ACCESS_TOKEN_EXPIRE_MINUTES30Access token 有效期（分鐘）

啟用 Keycloak 認證​

  1. 設定 ENABLE_AUTH=true
  2. 設定 Keycloak 相關環境變數
  3. 重新啟動服務
備註

啟用認證後，所有 API 端點將要求有效的 JWT token。

本地開發​

docker compose up -d workspace-manager

workspace-manager 在本地開發時應優先透過 Docker Compose 啟動，並配合完整 stack 一起運作。Compose 會將 ./workspace-manager 掛載到容器內的 /workspace-manager，因此程式碼修改通常可透過既有 reload 機制即時生效。

若尚未啟動其他相依服務，建議直接使用：

docker compose up -d

測試​

# 執行所有測試
pytest

# 執行測試並生成覆蓋率報告
pytest --cov=app --cov-report=html

# 容器化測試（推薦）
make test-workspaces

# lint 與靜態檢查
make lint-workspaces
容器化測試

建議優先使用容器化測試，避免本機缺少 PostgreSQL headers 或 Python 依賴造成驗證失敗。

監控​

服務URL說明
健康端點http://localhost:3001/health確認服務與 DB / Redis 狀態
Swagger UIhttp://localhost:3001/docs互動式 API 文件
ReDochttp://localhost:3001/redoc靜態 API 文件
Flowerhttp://localhost:5555Celery 任務監控