装不上？先看这里：ChengOS 安装故障排查导航（持续更新）
装不上？先看这里：ChengOS 安装故障排查导航
安装或首次运行遇到问题？别急，90% 的问题都在下面这四类里。花 2 分钟对号入座，大概率能自己解决；解决不了再发帖求助，带上文末的信息模板，回复会快很多。
30 秒自检清单
发帖/排查前，先确认这几项：
- ChengOS 版本（安装脚本输出或
cheng --version） - 部署模式：Docker 还是二进制（native）？
- 操作系统与架构（如 Ubuntu 22.04 / x86_64）
- 内存大小（512MB 机器请使用二进制模式，勿装 Docker）
- 完整的报错信息（截图或文本，不要只写"报错了"）
一、端口被占用
典型报错： Address already in use、服务启动后立刻退出。
ChengOS 默认使用 8080（API）、5173（UI 开发）、3000（App）等端口。排查方法：
# 查看端口占用
sudo lsof -i :8080
sudo ss -tlnp | grep 8080
解决：停掉占用进程，或在配置中修改端口后重启。详见 安装故障排查。
二、Docker 权限 / 镜像拉取失败
典型报错： permission denied（docker.sock）、pull access denied 或拉取超时。
- 权限问题：把当前用户加入 docker 组（
sudo usermod -aG docker $USER）后重新登录 - 拉取超时：多为网络原因，可配置国内镜像加速器
- 内存只有 1G 以下：强烈建议改用二进制安装，Docker 本身就要吃掉几百 MB
三、LLM 供应商报错
典型报错： 401 Unauthorized、model not found、连接超时。
- API Key 是否正确、是否已存入凭证保险库
- 模型名称是否与供应商文档一致（大小写敏感）
- 国内访问 OpenAI 等需配置代理
详见 LLM 供应商报错排查。
四、服务健康检查失败
浏览器打不开 UI、CLI 连不上服务时：
# 检查服务状态
curl http://localhost:8080/healthz
# 查看日志定位原因
日志位置与常见启动失败原因见 安装故障排查。
发帖求助模板
如果以上都没解决，发帖时请尽量带上：
- 版本：
- 部署模式：Docker / 二进制
- 系统：
- 做了什么：
- 期望结果：
- 实际结果 / 报错信息：
文档导航
| 主题 | 链接 |
|---|---|
| 安装指南 | /docs/install-chengos |
| 快速上手 | /docs/quickstart-first-workflow |
| 安装故障排查 | /docs/fix-install-issues |
| LLM 供应商报错 | /docs/fix-llm-provider-errors |
| FAQ | /docs/faq |
| 节点参考 | /docs/nodes-input-output |
| 社区 MCP 接入 | /docs/community-mcp-access |
本帖会持续更新。你踩过的坑如果不在上面，欢迎回复补充——你的经验会帮到下一个安装的人。