AI 助理
文档备案控制台
官方文档
输入文档关键字查找
首页

云端环境

更新时间：
复制为 MD 格式
产品详情
我的收藏

Environment 定义了 Session 运行的容器模板——操作系统、网络策略、预装依赖。你可以为不同场景创建不同的环境：严格隔离的安全审计环境、预装数据科学库的分析环境、或者开放网络的通用开发环境。

环境是什么

Environment 是 Session 的基础设施层：

  • 容器类型 — 目前支持 cloud（云端托管容器）

  • 网络策略 — 控制容器的出站网络访问

  • 依赖包 — 预装系统包、Python 包、Node.js 包

每个 Session 启动时会基于指定的 Environment 模板创建隔离的运行实例。

字段说明

字段

类型

必填

说明

id

string

—

系统生成，env_ 前缀

type

string

—

固定为 "environment"

name

string

是

环境名称

description

string

否

描述信息，默认 ""

config

object

是

环境配置（类型、网络、包）

config.type

string

是

容器类型，当前固定为 "cloud"

config.networking

object

否

网络策略；必须为对象，可选值为 {"type": "unrestricted" | "limited" | "allowed_hosts"}

config.packages

object

否

预装依赖包配置

status

string

—

环境状态：ready

archived

boolean

—

是否已归档，默认 false

archived_at

string|null

—

归档时间（ISO 8601），未归档时为 null

created_at

string

—

创建时间

updated_at

string

—

最后更新时间

网络策略

config.networking 支持三种模式，所有模式都必须使用对象格式（字符串简写如 "unrestricted" 不被支持，会返回 400）。

模式

值

说明

完全开放

{"type": "unrestricted"}

容器可以访问任意外部地址

受限

{"type": "limited", "allow_package_managers": true}

仅允许访问已知安全的公共服务和包管理器

白名单

{"type": "allowed_hosts", "allowed_hosts": [...]}

仅允许访问指定主机名

networking 对象字段

字段

类型

说明

networking.type

string

网络策略类型：unrestricted / limited / allowed_hosts

networking.allow_package_managers

boolean

limited 模式下是否允许包管理器（pip / npm / apt 等）访问

networking.allowed_hosts

array

allowed_hosts 模式下允许的主机名列表

完全开放

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"}
  }
}

适用于需要下载依赖、访问外部 API 的通用开发任务。

受限模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "limited",
      "allow_package_managers": true
    }
  }
}

适用于不需要任意外网访问、但仍需通过包管理器拉依赖的任务。

白名单模式

{
  "config": {
    "type": "cloud",
    "networking": {
      "type": "allowed_hosts",
      "allowed_hosts": [
        "api.github.com",
        "registry.npmjs.org",
        "pypi.org"
      ]
    }
  }
}

适用于安全合规要求高的场景，精确控制可访问的外部服务。

预装依赖

通过 config.packages 指定容器启动时预装的依赖：

{
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "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 运行时按需安装。

创建环境

# 创建一个数据科学专用环境
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
      }
    }
  }' | jq .

成功返回 201 Created：

{
  "id": "env_019e44eb66bb748cabcd1489f6fa4428",
  "type": "environment",
  "name": "data-science",
  "description": "",
  "config": {
    "type": "cloud",
    "networking": {"type": "unrestricted"},
    "packages": {
      "apt": ["build-essential"],
      "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter"]
    }
  },
  "status": "ready",
  "archived": false,
  "archived_at": null,
  "created_at": "2026-05-18T10:00:00Z",
  "updated_at": "2026-05-18T10:00:00Z"
}

创建安全受限环境

# 创建一个仅允许访问内部 API 的安全环境
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "secure-internal",
    "config": {
      "type": "cloud",
      "networking": {
        "type": "allowed_hosts",
        "allowed_hosts": ["internal-api.mycompany.com", "git.mycompany.com"]
      },
      "packages": {
        "apt": ["git", "curl"]
      }
    }
  }' | jq .

查询环境

# 列出所有环境
curl -s https://api.qoder.com.cn/api/v1/cloud/environments \
  -H "Authorization: Bearer $QODER_PAT"

# 获取单个环境详情
curl -s https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

更新环境

# 为已有环境添加新的依赖包
curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "data-science",
    "config": {
      "type": "cloud",
      "networking": {"type": "unrestricted"},
      "packages": {
        "apt": ["build-essential", "libpq-dev"],
        "pip": ["pandas", "numpy", "matplotlib", "scikit-learn", "jupyter", "sqlalchemy"]
      }
    }
  }' | jq .

更新环境不会影响已运行的 Session。新配置仅对后续创建的 Session 生效。

删除环境

# 删除自定义环境
curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/environments/env_ds456 \
  -H "Authorization: Bearer $QODER_PAT"

当 environment 仍被未归档的 session 引用时，DELETE 返回 409 "Environment is in use and cannot be deleted"。需要先归档/删除引用方 session，或改用 POST /environments/{id}/archive 软删（无引用约束）。

环境选型建议

场景

推荐配置

通用开发

default 环境，无需额外配置

数据分析

预装 pandas/numpy，开放网络

安全审计

白名单网络，最小依赖

前端开发

预装 Node.js 生态工具，开放 npm registry

CI/CD 集成

预装 git/docker CLI，白名单模式

常见问题

Q: 环境创建后需要等待多久才能使用？A: 环境创建后状态直接为 ready，可立即用于创建 Session。实际的容器初始化（包括安装依赖）发生在 Session 启动时。Q: 预装包的版本可以指定吗？A: pip 和 npm 包支持版本指定，如 "pandas==2.1.0" 或 "typescript@5.0.0"。apt 包使用系统源的默认版本。Q: networking 设置错误导致 Agent 运行失败怎么办？A: 创建一个新的环境（或更新现有环境），修改网络策略后重新启动 Session。Q: 一个账号最多能创建多少个环境？A: 无硬性限制，但建议按实际需求创建，避免管理混乱。建议通过命名规范分类。

上一篇：运行环境下一篇：容器参考