# 装不上？先看这里：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）等端口。排查方法：

```bash
# 查看端口占用
sudo lsof -i :8080
sudo ss -tlnp | grep 8080
```

解决：停掉占用进程，或在配置中修改端口后重启。详见 [安装故障排查](/docs/fix-install-issues)。

## 二、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 供应商报错排查](/docs/fix-llm-provider-errors)。

## 四、服务健康检查失败

浏览器打不开 UI、CLI 连不上服务时：

```bash
# 检查服务状态
curl http://localhost:8080/healthz
# 查看日志定位原因
```

日志位置与常见启动失败原因见 [安装故障排查](/docs/fix-install-issues)。

## 发帖求助模板

如果以上都没解决，发帖时请尽量带上：

```
- 版本：
- 部署模式：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 |

---

本帖会持续更新。你踩过的坑如果不在上面，欢迎回复补充——你的经验会帮到下一个安装的人。