Repository navigation
DevContainer
AI CLI 用于在 DevContainer 终端中直接使用常见 AI 编程工具。DevStar 可以通过启动脚本在创建开发容器时自动安装对应 CLI,并复用平台 AI 设置中的模型密钥、Base URL 和模型配置,减少进入容器后的手动安装和配置步骤。
- 打开需要使用 AI CLI 的仓库,点击 设置 → 开发容器 → 脚本管理。
- 在 启动脚本 区域点击 + New Script。
- 输入下面的脚本名,并按 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_* 配置。
- 回到仓库页面,点击顶部的 开发容器。
- 在右侧 容器管理 操作区点击 创建开发容器。
- 等待 DevContainer 创建完成。
创建过程中,DevStar 会执行刚才添加的启动脚本并使用变量/密钥,完成安装配置 Claude Code。
如果之前已经创建过 DevContainer,需要删除后重新创建,新添加的启动脚本才会执行。
- DevContainer 创建完成后,在 开发容器 页面点击 使用 WebTerminal 打开,或用 VS Code / Cursor 等方式打开项目,即进入了DevContainer开发容器中的项目目录:
例如仓库名是 vitepress:
root@df508de70a88:/workspaces/vitepress# - 先检查 Claude Code 是否安装成功:
claude --version- 执行 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相关项目的在线运行调试。
在仓库根目录的 .devcontainer/devcontainer.json 中添加 forwardPorts:
{
"name": "My Project",
"image": "node:18",
"forwardPorts": [3000, 5173, 8080],
"postCreateCommand": "npm install && npm run dev"
}说明:
-
forwardPorts: 声明要转发的端口列表 - 示例中配置了 3000、5173、8080 三个端口
- 在仓库页面点击顶部 开发容器
- 点击右侧 创建开发容器
- 等待容器创建完成
容器启动后,在 开发容器 详情页右侧会显示 端口转发 模块:
端口转发
━━━━━━━━━━━━━━━━━━
● 已启动 :5173 🔗
等待中 :3000
等待中 :8080
- 已启动(绿色):端口可以访问,点击 🔗 图标在新标签页打开
- 等待中(灰色):端口还没有服务监听,或服务尚未启动
点击已启动端口旁的链接图标,即可在浏览器中访问容器内的服务。
如果你运行的是 VitePress、Vite、React、Vue 等前端开发服务器,需要额外配置 base 路径,否则会出现资源 404 错误。
因为端口转发的访问地址是:
https://devstar.com/用户名/仓库名/devcontainer/forwardPorts/5173/
而不是:
http://localhost:5173/
如果不配置 base,VitePress 会认为自己运行在根目录 /,生成的资源路径(如 /assets/style.css)无法正确访问,导致 CSS、JavaScript 等资源加载失败(404 错误)。
修改 .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
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 让开发服务器监听所有网络接口,这样平台才能访问容器内的服务。
- 创建 DevContainer
- 等待端口状态变为 已启动
- 点击链接图标打开网站
- 检查:
- ✅ 页面正常显示
- ✅ 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在应用配置中读取这些环境变量即可。
A: 如果运行的是 VitePress、Vite 等前端开发服务器,不配置 base 会导致:
- CSS、JavaScript、图片等资源返回 404 错误
- 页面样式丢失或功能异常
- 导航链接无法正确跳转
- HMR 热更新失效
纯后端 API 服务不需要配置 base。
A: 不会。通过 ?? 或 || 设置默认值:
const base = process.env.DEVSTAR_FORWARD_PORT_BASE_5173 ?? '/'本地开发时环境变量不存在,自动使用 /,不影响本地开发体验。
A: 可能的原因:
- 容器内的服务还没启动完成(等待一会)
- 服务监听的是
localhost而不是0.0.0.0(改成--host 0.0.0.0) - 端口号配置错误(检查
forwardPorts和实际服务端口是否一致) - 服务启动失败(在 WebTerminal 中检查服务状态)
A: 目前支持:
- ✅ HTTP
- ✅ HTTPS
- ✅ WebSocket (ws/wss)
不支持:
- ❌ 原始 TCP/UDP 端口转发
A: 可以!在 forwardPorts 中配置多个端口:
{
"forwardPorts": [3000, 5173, 8080, 9000]
}每个端口都会在详情页显示,并提供独立的访问链接。
适用于基于 DevStar DevContainer 的嵌入式开发项目,项目在 DevContainer 中编译,QEMU、OpenOCD、J-Link GDB Server 或真实设备服务运行在开发者电脑上,DevStar负责在两端之间转发调试流量和固件产物,详细使用方法...
Copyright ©Mengning Software 2024-2026 All rights reserved.