Skip to content

DevContainer

DevStar Bot edited this page Sep 3, 2026 · 5 revisions

DevContainer 容器化开发环境

AI CLI based on DevContainer

AI CLI 用于在 DevContainer 终端中直接使用常见 AI 编程工具。DevStar 可以通过启动脚本在创建开发容器时自动安装对应 CLI,并复用平台 AI 设置中的模型密钥、Base URL 和模型配置,减少进入容器后的手动安装和配置步骤。

添加启动脚本

  1. 打开需要使用 AI CLI 的仓库,点击 设置 → 开发容器 → 脚本管理。
  2. 在 启动脚本 区域点击 + New Script。
  3. 输入下面的脚本名,并按 Enter 保存:
DEVSTAR_INSTALL_CLAUDE_CODE

DEVSTAR_INSTALL_CLAUDE_CODE 表示:创建 DevContainer 时自动安装 Claude Code CLI。

  • 容器密钥环境配置与 AI Setting 复用

如果在 DevStar 的 AI 设置 → API 设置 中配置了 API Key、Base URL 和 Model,创建 DevContainer 时会和启动脚本一并自动注入到容器环境变量中:

LLM_API_KEY
LLM_BASE_URL
LLM_MODEL

AI CLI 启动脚本会优先使用自己的设置密钥/变量,在变量管理 → 密钥/变量中设置,例如 Claude Code 的 ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL、ANTHROPIC_MODEL;如果没有配置工具专属变量,则自动复用上面的 LLM_* 配置。

创建开发容器

  1. 回到仓库页面,点击顶部的 开发容器。
  2. 在右侧 容器管理 操作区点击 创建开发容器。
  3. 等待 DevContainer 创建完成。

创建过程中,DevStar 会执行刚才添加的启动脚本并使用变量/密钥,完成安装配置 Claude Code。

如果之前已经创建过 DevContainer,需要删除后重新创建,新添加的启动脚本才会执行。

在项目目录下执行 Claude

  1. DevContainer 创建完成后,在 开发容器 页面点击 使用 WebTerminal 打开,或用 VS Code / Cursor 等方式打开项目,即进入了DevContainer开发容器中的项目目录:

例如仓库名是 vitepress:

root@df508de70a88:/workspaces/vitepress# 
  1. 先检查 Claude Code 是否安装成功:
claude --version
  1. 执行 Claude Code:
claude

如果还需要其他 AI CLI,可以继续点击 + New Script,再输入对应脚本名:

AI CLI 启动脚本名 容器内执行命令
Claude Code DEVSTAR_INSTALL_CLAUDE_CODE claude
Gemini CLI DEVSTAR_INSTALL_GEMINI gemini
iFlow CLI DEVSTAR_INSTALL_IFLOW_CLI iflow
OpenCode DEVSTAR_INSTALL_OPENCODE opencode
Qwen CLI DEVSTAR_INSTALL_QWEN_CLI qwen
Codex CLI DEVSTAR_INSTALL_CODEX_CLI codex

添加脚本可以自定义任意Bash脚本

  • 脚本标签和优先级说明

脚本列表中的标签表示脚本来源:

标签 含义
User 当前用户配置的脚本
Repo 当前仓库配置的脚本
Org 当前组织配置的脚本
Global 管理后台配置的全局脚本
devstar.cn DevStar 平台提供的默认脚本

同名脚本按以下优先级生效:

User > Repo > Org > Global > devstar.cn

在设置中AI设置 > API设置里配置LLM_API_KEY、LLM_BASE_URL和LLM_MODEL为DeepSeek API和OpenAI API的测试结果:

CLI 工具 环境变量 / 配置方式 deepseek-chat 兼容性 gpt-5.5 兼容性
Claude Code ANTHROPIC_API_KEY / ANTHROPIC_BASE_URL / ANTHROPIC_MODEL ✅ 正常识别配置,但不支持该 API / 模型协议 ✅ 正常识别配置,但 OpenAI gpt-5.5 不是 Claude Code 适配模型
Gemini CLI GEMINI_API_KEY / GOOGLE_API_KEY / GEMINI_MODEL / GEMINI_CLI_TRUST_WORKSPACE ✅ 正常识别配置,但 Gemini CLI 走 Google API,不支持 DeepSeek API ✅ 正常识别配置,但 Gemini CLI 走 Google API,不支持 OpenAI API
OpenCode OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL + opencode.json + auth.json ✅ 可以正常使用 deepseek-chat ✅ 可以正常使用 gpt-5.5
Qwen CLI QWEN_API_KEY / QWEN_BASE_URL / QWEN_MODEL + OpenAI-compatible 配置 ✅ 可以正常使用 deepseek-chat ✅ 可以正常使用 gpt-5.5
Codex CLI OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL + ~/.codex/config.toml ✅ 正常识别配置,但 DeepSeek 不支持 Codex 使用的 /responses API ✅ 可以正常使用 gpt-5.5
iFlow CLI IFLOW_API_KEY / IFLOW_BASE_URL / IFLOW_MODEL_NAME + ~/.iflow/settings.json ✅ 可以正常使用 deepseek-chat ✅ 可以正常使用 gpt-5.5

端口转发功能

DevContainer 支持端口转发,让你可以在浏览器中直接访问容器内运行的 Web 服务(如开发服务器、文档网站、API 服务等),实现完全云原生的Web相关项目的在线运行调试。

快速开始

1. 配置要转发的端口

在仓库根目录的 .devcontainer/devcontainer.json 中添加 forwardPorts:

{
  "name": "My Project",
  "image": "node:18",
  "forwardPorts": [3000, 5173, 8080],
  "postCreateCommand": "npm install && npm run dev"
}

说明:

  • forwardPorts: 声明要转发的端口列表
  • 示例中配置了 3000、5173、8080 三个端口

2. 创建 DevContainer

  1. 在仓库页面点击顶部 开发容器
  2. 点击右侧 创建开发容器
  3. 等待容器创建完成

3. 访问转发的端口

容器启动后,在 开发容器 详情页右侧会显示 端口转发 模块:

端口转发
━━━━━━━━━━━━━━━━━━
● 已启动 :5173  🔗
  等待中 :3000
  等待中 :8080
  • 已启动(绿色):端口可以访问,点击 🔗 图标在新标签页打开
  • 等待中(灰色):端口还没有服务监听,或服务尚未启动

点击已启动端口旁的链接图标,即可在浏览器中访问容器内的服务。


特殊配置:VitePress / Vite / 前端框架

如果你运行的是 VitePress、Vite、React、Vue 等前端开发服务器,需要额外配置 base 路径,否则会出现资源 404 错误。

为什么需要配置?

因为端口转发的访问地址是:

https://devstar.com/用户名/仓库名/devcontainer/forwardPorts/5173/

而不是:

http://localhost:5173/

如果不配置 base,VitePress 会认为自己运行在根目录 /,生成的资源路径(如 /assets/style.css)无法正确访问,导致 CSS、JavaScript 等资源加载失败(404 错误)。

VitePress 配置示例

修改 .vitepress/config.js 或 .vitepress/config.mts:

import { defineConfig } from 'vitepress'

// 从环境变量读取 base path(平台会自动注入)
const base = process.env.DEVSTAR_FORWARD_PORT_BASE_5173?.replace(/\/?$/, '/') ?? '/'
const origin = process.env.DEVSTAR_FORWARD_PORT_ORIGIN

export default defineConfig({
  title: '我的文档',
  description: '项目文档',
  base,  // 关键配置:使用环境变量设置 base path
  
  vite: {
    server: {
      // 设置外部访问的域名
      ...(origin ? { origin } : {}),
      // 修正 HMR WebSocket 路径
      ...(base !== '/' ? { hmr: { path: `${base}@vite/` } } : {}),
    }
  }
})

关键点:

  • base: 从 DEVSTAR_FORWARD_PORT_BASE_5173 环境变量读取
  • 本地开发时环境变量不存在,自动使用 /(不影响本地开发)
  • 在 DevContainer 中,平台会自动注入正确的路径

其他框架配置

框架 配置文件 配置示例
Vite vite.config.js base: process.env.DEVSTAR_FORWARD_PORT_BASE_5173 ?? '/'
Next.js next.config.js basePath: process.env.DEVSTAR_FORWARD_PORT_BASE_3000 ?? ''
Create React App .env PUBLIC_URL=/path/to/app/
Vue CLI vue.config.js publicPath: process.env.DEVSTAR_FORWARD_PORT_BASE_3000 ?? '/'
Angular angular.json "baseHref": process.env.DEVSTAR_FORWARD_PORT_BASE_4200 ?? '/'

注意: 环境变量名称中的端口号要和你配置的 forwardPorts 一致:

  • 端口 5173 → DEVSTAR_FORWARD_PORT_BASE_5173
  • 端口 3000 → DEVSTAR_FORWARD_PORT_BASE_3000

完整示例:VitePress 项目

1. .devcontainer/devcontainer.json

{
  "name": "VitePress Docs",
  "image": "node:18",
  "forwardPorts": [5173],
  "postCreateCommand": "npm install && npm run docs:dev"
}

2. .vitepress/config.js

import { defineConfig } from 'vitepress'

const base = process.env.DEVSTAR_FORWARD_PORT_BASE_5173?.replace(/\/?$/, '/') ?? '/'
const origin = process.env.DEVSTAR_FORWARD_PORT_ORIGIN

export default defineConfig({
  title: '项目文档',
  base,
  vite: {
    server: {
      ...(origin ? { origin } : {}),
      ...(base !== '/' ? { hmr: { path: `${base}@vite/` } } : {}),
    }
  }
})

3. package.json

{
  "scripts": {
    "docs:dev": "vitepress dev docs --host 0.0.0.0"
  }
}

说明: --host 0.0.0.0 让开发服务器监听所有网络接口,这样平台才能访问容器内的服务。

测试是否配置正确

  1. 创建 DevContainer
  2. 等待端口状态变为 已启动
  3. 点击链接图标打开网站
  4. 检查:
    • ✅ 页面正常显示
    • ✅ CSS 样式正常加载
    • ✅ 图片和其他资源正常显示
    • ✅ 导航链接可以跳转
    • ✅ 修改 Markdown 文件后页面自动刷新(HMR 正常)

如果出现资源 404 错误或样式丢失,说明 base 配置有问题,请检查:

  • 是否正确读取了环境变量 DEVSTAR_FORWARD_PORT_BASE_*
  • 环境变量名称中的端口号是否和 forwardPorts 一致

注入的环境变量

平台会在容器启动时自动注入以下环境变量:

# 每个端口都有专属的 base path
DEVSTAR_FORWARD_PORT_BASE_5173=/user/repo/devcontainer/forwardPorts/5173/
DEVSTAR_FORWARD_PORT_BASE_3000=/user/repo/devcontainer/forwardPorts/3000/

# 第一个端口的简写(如果有多个端口)
DEVSTAR_FORWARD_PORT_BASE=/user/repo/devcontainer/forwardPorts/5173/

# 平台的域名
DEVSTAR_FORWARD_PORT_ORIGIN=https://devstar.example.com

在应用配置中读取这些环境变量即可。


常见问题

Q: 不配置 base 会怎样?

A: 如果运行的是 VitePress、Vite 等前端开发服务器,不配置 base 会导致:

  • CSS、JavaScript、图片等资源返回 404 错误
  • 页面样式丢失或功能异常
  • 导航链接无法正确跳转
  • HMR 热更新失效

纯后端 API 服务不需要配置 base。

Q: 本地开发时环境变量不存在会有问题吗?

A: 不会。通过 ?? 或 || 设置默认值:

const base = process.env.DEVSTAR_FORWARD_PORT_BASE_5173 ?? '/'

本地开发时环境变量不存在,自动使用 /,不影响本地开发体验。

Q: 端口一直显示"等待中"怎么办?

A: 可能的原因:

  1. 容器内的服务还没启动完成(等待一会)
  2. 服务监听的是 localhost 而不是 0.0.0.0(改成 --host 0.0.0.0)
  3. 端口号配置错误(检查 forwardPorts 和实际服务端口是否一致)
  4. 服务启动失败(在 WebTerminal 中检查服务状态)

Q: 支持哪些协议?

A: 目前支持:

  • ✅ HTTP
  • ✅ HTTPS
  • ✅ WebSocket (ws/wss)

不支持:

  • ❌ 原始 TCP/UDP 端口转发

Q: 可以转发多个端口吗?

A: 可以!在 forwardPorts 中配置多个端口:

{
  "forwardPorts": [3000, 5173, 8080, 9000]
}

每个端口都会在详情页显示,并提供独立的访问链接。


适用于基于 DevStar DevContainer 的嵌入式开发项目,项目在 DevContainer 中编译,QEMU、OpenOCD、J-Link GDB Server 或真实设备服务运行在开发者电脑上,DevStar负责在两端之间转发调试流量和固件产物,详细使用方法...

Clone this wiki locally