Environment 定义 Session 使用的运行环境，包括环境类型、预装依赖、启动脚本和 metadata。你可以使用默认托管环境，也可以为特定任务创建预装工具的环境或接入自托管执行环境。
环境是什么
Environment 是 Session 的基础设施层：
- 环境类型 -
cloud 表示云端托管容器，self_hosted 表示自托管执行环境
- 依赖包 - 预装系统包、Python 包、Node.js 包
- 启动脚本 - 容器准备阶段、依赖安装完成后执行的用户脚本
每个 Session 启动时会基于指定的 Environment 模板创建独立的运行实例。
字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|
id | string | - | 系统生成，env_ 前缀 |
type | string | - | 固定为 "environment" |
name | string | 是 | 环境名称 |
description | string | 否 | 描述信息，默认 "" |
config | object | 否 | 环境配置；省略时默认为 {"type":"cloud"} |
config.type | string | config 存在时是 | 环境类型："cloud" 或 "self_hosted" |
config.packages | object | 否 | cloud 环境的预装依赖包配置 |
config.setup_script | string | 否 | sandbox 准备阶段执行的 shell 脚本（最大 64 KB） |
metadata | object | 否 | 自定义 key/value metadata |
archived_at | string|null | - | 归档时间（ISO 8601），未归档时为 null |
created_at | string | - | 创建时间 |
updated_at | string | - | 最后更新时间 |
Config 类型
config.type 可以是 "cloud" 或 "self_hosted"。
self_hosted 的 config 可以只包含类型，也可以包含 setup_script：
Self-hosted Environment 不会启动托管云端容器。外部 worker 通过 Work API poll、ack、heartbeat 和 stop 该 Environment 下的 Session work。self_hosted config 仅支持 type 和可选的 setup_script。
cloud 的 config 可以包含 packages 和 setup_script。
预装依赖
通过 config.packages 指定容器启动时预装的依赖：
{
"config": {
"type": "cloud",
"packages": {
"apt": ["git", "build-essential", "libssl-dev"],
"pip": ["pandas", "numpy", "scikit-learn"],
"npm": ["typescript", "eslint", "prettier"]
}
}
}
| 包管理器 | 字段 | 说明 |
|---|
| apt | packages.apt | Debian/Ubuntu 系统包 |
| pip | packages.pip | Python 包 |
| npm | packages.npm | Node.js 包 |
预装依赖会增加环境初始化时间。只添加确实需要的包，其余可在 Session 运行时按需安装。
启动脚本
config.setup_script 是一段在 sandbox 准备阶段、packages 安装完成之后执行的 shell 脚本，使用 /bin/bash -lc 解释器运行。常用于克隆代码、写配置文件、warmup 缓存等无法用 packages 表达的初始化步骤。
| 约束 | 值 |
|---|
| 类型 | string |
| 最大长度 | 64 KB |
| 解释器 | /bin/bash -lc |
| 超时 | 10 分钟 |
| 执行时机 | sandbox 准备阶段，packages 安装完成之后 |
# 创建一个会自动 clone 项目并预装依赖的环境
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "node-with-init",
"config": {
"type": "cloud",
"packages": {
"npm": ["pnpm@9"]
},
"setup_script": "set -euo pipefail\n[ -d /data/workspace/repo/.git ] || git clone https://github.com/me/repo /data/workspace/repo\ncd /data/workspace/repo && pnpm install --frozen-lockfile"
}
}' | jq .
创建环境
# 创建一个数据科学专用环境
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "data-science",
"config": {
"type": "cloud",
"packages": {
"apt": ["build-essential"],
"pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
}
}
}' | jq .
{
"id": "env_019e44eb66bb748cabcd1489f6fa4428",
"type": "environment",
"name": "data-science",
"description": "",
"config": {
"type": "cloud",
"packages": {
"type": "packages",
"apt": ["build-essential"],
"cargo": [],
"gem": [],
"go": [],
"npm": [],
"pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
}
},
"metadata": {},
"archived_at": null,
"created_at": "2026-05-18T10:00:00Z",
"updated_at": "2026-05-18T10:00:00Z"
}
查询环境
# 列出所有环境
curl -s https://api.qoder.com/api/v1/cloud/environments \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN"
# 获取单个环境详情
curl -s https://api.qoder.com/api/v1/cloud/environments/env_ds456 \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN"
更新环境
# 为已有环境添加新的依赖包
curl -s -X POST https://api.qoder.com/api/v1/cloud/environments/env_ds456 \
-H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "data-science",
"config": {
"type": "cloud",
"packages": {
"apt": ["build-essential", "libpq-dev"],
"pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
}
}
}' | jq .
更新环境不会影响已运行的 Session。新配置仅对后续创建的 Session 生效。
环境选型建议
| 场景 | 推荐配置 |
|---|
| 通用开发 | default 环境，无需额外配置 |
| 数据分析 | 预装 pandas/numpy，并验证依赖源连通性 |
| 前端开发 | 预装 Node.js 生态工具，并验证 npm registry 连通性 |
| CI/CD 集成 | 预装所需 CLI，并在目标环境中验证依赖服务连通性 |
常见问题
Q: 环境创建后需要等待多久才能使用？
A: 环境创建后可立即用于创建 Session。实际的容器初始化（包括安装依赖）发生在 Session 启动时。
Q: 预装包的版本可以指定吗？
A: pip 和 npm 包支持版本指定，如 "pandas==2.1.0" 或 "typescript@5.0.0"。apt 包使用系统源的默认版本。
Q: 一个账号最多能创建多少个环境？
A: 无硬性限制，但建议按实际需求创建，避免管理混乱。建议通过命名规范分类。
下一步
