启动命令配置规范

1. 核心概念

在 共绩算力 平台中，您填写的”启动命令”对应于容器的 command（容器启动命令）和 args（命令参数）字段。

• command：对应 Docker 的 ENTRYPOINT，是容器的主进程
• args：对应 Docker 的 CMD，是传递给主进程的参数

1.1 配置示例场景

当您自己打包上传的镜像未配置启动命令时，需要手动配置启动命令。以下是典型示例：

vllm 镜像中启动模型 示例：

vllm serve Qwen/Qwen3-VL-8B-Instruct-FP8 --max-model-len 32K --max-num-seqs 4 --limit-mm-per-prompt '{"image":4,"video":0}' --mm-processor-cache-gb 0

Indextts 镜像示例：

GRADIO_ROOT_PATH=$(echo "$HOSTNAME" | sed -E 's,^(([^-]+-){3}).*,https://\17860.550c.cloud,') .venv/bin/python webui.py

Sora2 API 镜像调用示例：

/bin/bash


-c


cd /root && bash run.sh

2. 常见问题分类

启动命令配置问题主要分为以下几类：

常见启动命令问题分类与检测要点

错误类型	检测要点
格式错误	缺少引号、尾逗号、引号不匹配（如使用双引号未转义）
	参数之间缺少必要的空格
	错误的大小写使用（如参数名或值的大小写不正确）
参数错误	参数值超出范围（如数值过大或过小）
	参数值不符合要求（如模型名拼写错误、路径错误）
	必要参数遗漏（如缺少关键的启动参数）
	重复参数导致冲突（如同一参数多次出现）
命令拆分	错误地将命令主体（如 ENTRYPOINT）和参数（如 CMD）混淆
	未正确拆分命令主体和参数，导致命令无法正确解析
特殊字符	使用了不被支持的特殊字符（如中文标点、换行符等）
测试不足	未在本地或测试环境中验证命令的有效性，导致容器启动失败
缓存问题	指定的缓存路径不可用或权限不足，导致命令执行失败
顺序问题	参数顺序错误，导致命令解析失败

3. 错误案例与解决方案

3.1 引号与转义问题

错误示例：

--limit-mm-per-prompt {"image":4,"video":0}

错误现象： Shell 把花括号当成通配符，报错 cannot find file 4

正确写法：

--limit-mm-per-prompt '{"image":4,"video":0}'

错误示例：

--limit-mm-per-prompt "{\"image\":4,\"video\":0}"

错误现象： 平台把 \" 当普通字符，JSON 解析失败

正确写法： 改用单引号包裹整段 JSON，内部用双引号即可

--limit-mm-per-prompt '{"image":4,"video":0}'

3.2 空格缺失问题

错误示例：

--mm-processor-cache-gb0

错误现象： 识别不出参数，提示 unknown flag -gb0

正确写法：

--mm-processor-cache-gb 0

3.3 大小写问题

错误示例：

--max-model-len 32k

错误现象： 日志报错 Unit suffix must be upper-case

正确写法：

--max-model-len 32K

3.4 模型名大小写问题

错误示例：

qwen/qwen3-vl-8b-instruct-fp8

错误现象： 远端返回 repository not found

正确写法： 严格按官方大小写

Qwen/Qwen3-VL-8B-Instruct-FP8

3.5 数值越界问题

错误示例：

--max-num-seqs 4

错误现象： 启动即崩溃，日志 ValueError: 4 < minimum 16

正确写法： 改到允许范围

--max-num-seqs 16

3.6 必传子命令缺失

错误示例：

vllm

错误现象： 容器立即退出，提示 missing sub-command

正确写法： 运行参数第一格补 serve

vllm serve

3.7 参数重复问题

错误示例： 表单里填 --max-model-len 32K，又在”添加启动参数”里写一遍 --max-model-len 32K

错误现象： 命令行出现两次，vLLM 报 duplicate argument

正确写法： 只保留一处

3.8 顺序敏感问题

错误示例：

serve --limit-mm-per-prompt '{"image":4}' Qwen/...

错误现象： 旧版本 vLLM 把 JSON 当模型路径，报 file not found

正确写法： 模型名紧跟 serve，选项放前面

vllm serve Qwen/Qwen3-VL-8B-Instruct-FP8 --limit-mm-per-prompt '{"image":4}'

3.9 特殊字符问题

错误示例： JSON 尾逗号

{"image":4,"video":0,}

错误现象： 严格解析器报错 trailing comma

正确写法： 去掉尾逗号

{"image":4,"video":0}

3.10 平台转义问题

错误示例： YAML 表单填 --limit-mm-per-prompt '{"image":4}' 后，平台渲染成 map[image:4]

错误现象： 容器启动失败

正确写法： 在 YAML 中用单引号包裹整行，或对 { 进行双引号转义

3.11 Windows 换行问题

错误示例： 脚本里出现 \r--max-model-len

错误现象： 报错 \r--max-model-len: command not found

正确写法： 使用 dos2unix 转换或在编辑器中选择 LF 换行

4. Docker 到 Kubernetes 命令转换指南

4.1 端口映射转换

Docker 中的 -p 8080:80 应该通过平台设置暴露端口，而不是加到启动参数里面。在平台配置界面中设置端口映射即可。

4.2 存储卷挂载转换

Docker 中的 -v data:data 在平台对应的是设置对象存储加速或者共享存储卷。在平台配置界面中设置存储卷挂载即可。

4.3 环境变量转换

Docker 中的 -e KEY=VALUE 在 Kubernetes 中通过环境变量配置，在平台配置界面中设置环境变量即可。

4.4 覆盖规则与冲突排查 入口点（ENTRYPOINT / CMD）

只要在平台表单里填写了「启动命令」，就等于把镜像里原来的 ENTRYPOINT 和/或 CMD 全部或部分替换；不写才保留镜像默认值。 很多“格式明明对却起不来”的案例，本质是两段命令打架，而非语法错误。

镜像里自带	平台里填写	最终生效的进程（数组拼接）	常见现象
ENTRYPOINT ["/start.sh"] CMD ["python","app.py"]	只填 args → ["vllm","serve","..."]	/start.sh vllm serve ...	报错“vllm 找不到”——脚本并不认识该子命令
ENTRYPOINT ["python"] CMD ["app.py"]	填 command → ["vllm","serve","..."]	vllm serve ...（python 被整体替换）	正常启动
ENTRYPOINT ["tini","--","python"] CMD ["app.py"]	只填 args → ["vllm","serve","..."]	tini -- python vllm serve ...	信号代理仍在，但 python 把 vllm 当模块名，报 No module named vllm
ENTRYPOINT [] CMD []	填 command + args	完全按平台填写执行	最可控，推荐

4.4.1 快速自检三步法

1. docker inspect <镜像> | jq '.[0].Config.Entrypoint, .[0].Config.Cmd' 看清镜像“出厂设置”。
2. 把「平台要填的 command / args」与上一步结果拼成一行数组，确认是否合法。
3. 本地先验证： docker run --rm -it --entrypoint <command> <镜像> <args...> 能跑通再贴到平台，可排除 90% 的“冲突型”启动失败。

4.4.2 平台使用策略

场景	建议
镜像作者已提供完整启动脚本（ENTRYPOINT）	仅使用 args，不要写 command；否则就把脚本完全覆盖掉。
镜像只给了 CMD，ENTRYPOINT 为空	可写 command，也可只写 args；推荐写 command，语义清晰。
需要完全掌控启动流程	在平台一次性写全 command，把镜像 ENTRYPOINT 覆盖掉；args 留空或继续追加参数。
不确定镜像逻辑	先用调试命令 ["sleep","infinity"] 让容器常驻，再 exec 进去手工跑一遍，看看到底需要哪一段。

一旦在平台配置 command，就等于把 Dockerfile 里的 ENTRYPOINT 整体替换

写下 args，就等于把 Dockerfile 里的 CMD 整体替换

先想清楚要保留哪一段，再把缺失的补全，就不会再冲突

5. 调试命令

5.1 保持容器运行

当您的任务没有主进程时，容器会反复重启，可使用以下调试命令保持容器运行：

方案 A：使用 sleep 命令

command: ["sleep", "infinity"]

内核调度器永远不会给该进程设置唤醒时间，因此只有收到信号才会返回。可响应 SIGTERM，容器停止时能做到优雅退出（< 10 ms 级返回）。

方案 B：使用 tail 命令

command: ["tail", "-f", "/dev/null"]

tail 阻塞在 read() 上，永远等不到新数据，于是进程永不结束。同样几乎不占 CPU，但比 sleep 多一次不必要的文件描述符打开。

5.2 使用场景

• 镜像打包后需要进入容器手动调试
• 应用启动失败需要排查环境问题
• 测试存储卷挂载、网络连通性等基础环境

5.3 调试步骤

1. 使用调试命令启动容器
2. 通过 Web 终端或 exec 进入容器
3. 手动执行命令排查问题
4. 修复问题后更新启动命令

6. 最佳实践

6.1 命令格式规范

1. 参数分隔：参数与值之间必须使用空格分隔

2. 引号使用：JSON 格式参数使用单引号包裹，内部使用双引号

3. 大小写敏感：严格按照官方文档的大小写要求配置参数和值

6.2 参数配置建议

1. 避免重复参数：同一参数只在一处配置，避免在多个位置重复设置

2. 参数顺序：遵循工具要求的参数顺序，通常模型名应紧跟子命令

3. 数值范围：确保参数值在允许范围内，避免越界错误

4. 必要参数：确保所有必要的启动参数都已配置

6.3 测试验证

1. 本地测试：在本地环境验证命令的有效性

2. 测试环境：在测试环境中验证命令配置

3. 日志检查：启动后检查容器日志，确认命令执行正常

4. 功能验证：验证应用功能是否正常

6.4 常见注意事项

1. 换行符：Windows 环境下注意使用 LF 换行符，避免 \r 字符导致命令解析失败

2. 特殊字符：避免使用中文标点等不被支持的特殊字符

3. 路径配置：确保路径配置正确，使用绝对路径

4. 权限问题：确保缓存路径等目录具有正确的访问权限

7.参考文档

k8s 中启动命令相关文档：

https://kubernetes.io/zh-cn/docs/tasks/inject-data-application/define-command-argument-container/

https://kubernetes.io/zh-cn/docs/tasks/debug/debug-application/get-shell-running-container/

https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#container-v1-core

https://docs.docker.com/reference/dockerfile#entrypoint

https://docs.docker.com/reference/dockerfile#cmd