AI 部署指南

Appearance

AI Agent 部署十大常见坑 ​

一句话 ​

刚接触 AI Agent 时踩的坑，我们替你踩过了。这 10 个问题是国内开发者最常遇到的，搞定了它们，Agent 部署就顺了。

🤖 AI Agent 快速入口

curl -H "Accept: text/markdown" https://doc.k4b.cn/best-practices/common-pitfalls.md

🥇 坑一：GitHub clone 超时 ​

现象：git clone 执行到一半卡住不动，或者直接 Failed to connect to github.com port 443: Timed out

原因：GitHub 在国内访问不稳定，直连经常超时

解决：

bash
# 方案 A（推荐）：通过 ghproxy 镜像加速
git clone https://ghproxy.com/https://github.com/xxx/project.git

# 方案 B：设置 git 代理
git config --global http.proxy http://127.0.0.1:7890
git clone https://github.com/xxx/project.git
# 用完取消代理
git config --global --unset http.proxy

详见完整方案：GitHub 项目国内镜像获取指南

🥈 坑二：npm install 装到一半卡死 ​

现象：npm install 跑到 resolve 阶段就停了，等 10 分钟都没反应

原因：npm 默认 registry 是 https://registry.npmjs.org，国内访问慢

解决：

bash
# 配置淘宝/华为云镜像
npm config set registry https://registry.npmmirror.com

# 或者用 cnpm（但不推荐，可能遇到包版本不一致问题）
# 推荐直接配 registry，原生命令最稳

🥉 坑三：API 请求一直超时 ​

现象：Agent 启动后，调用 AI 模型时卡住，最终报 Timeout / Connection Error

原因：海外 API（OpenAI、Claude）国内直连不通

解决：

  • 配代理：export HTTPS_PROXY=http://127.0.0.1:7890
  • 或者用国内中转 API（改 BASE_URL 即可）

4️⃣ 坑四：改了 base_url 还是连不上 ​

现象：配置了 OPENAI_BASE_URL=https://中转站/v1，但请求 404

原因：常见的路经问题——

  • 中转站 URL 末尾漏了 /v1
  • 协议写成了 http 但中转站只支持 https
  • API Key 格式不匹配（中转站和官方 key 格式不同）

解决：仔细检查中转站文档。大多数中转站的格式是：

OPENAI_BASE_URL=https://你的域名/v1

确保 key 是用中转站给的，不是官方的。

5️⃣ 坑五：Python 虚拟环境忘记激活 ​

现象：pip install 装了一堆，但运行时说模块找不到

原因：安装到了系统 Python，但 Agent 用的是虚拟环境

解决：

bash
# 创建虚拟环境
python -m venv .venv

# 激活（重要！）
# Windows:
.venv\Scripts\activate
# Mac/Linux:
source .venv/bin/activate

# 确定激活后 pip install
pip install -r requirements.txt

6️⃣ 坑六：Docker pull 镜像失败 ​

现象：docker pull 报 i/o timeout 或 not found

原因：Docker Hub 被墙 / 镜像在国外

解决：

bash
# 配置 Docker Hub 国内镜像
# 编辑 /etc/docker/daemon.json
{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://hub-mirror.c.163.com"
  ]
}

# 重启 Docker
sudo systemctl restart docker

7️⃣ 坑七：Node.js 版本不兼容 ​

现象：Agent 框架要求 Node 18+，但服务器上装的是 Node 16

解决：

bash
# 用 nvm 管理 Node 版本
curl -o- https://ghproxy.com/https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

# 安装 Node 18+
nvm install 18
nvm use 18

8️⃣ 坑八：忘记了 .env 文件 ​

现象：代码跑起来了，但报 API_KEY is not defined

原因：很多项目的 .env 是 .gitignore 里的，clone 下来没有

解决：项目目录里找 .env.example 或 .env.template，复制一份：

bash
cp .env.example .env
# 然后编辑 .env 填入真实 key

9️⃣ 坑九：端口被占用 ​

现象：npm run dev 后报 Port 3000 already in use

解决：

bash
# 查谁占了端口
lsof -i :3000

# 杀掉占用进程
kill -9 PID

# 或者换个端口（大多数框架支持 PORT 环境变量）
PORT=3001 npm run dev

🔟 坑十：用 root 跑 npm 项目 ​

现象：在服务器上用 sudo npm run dev 启动，各种权限问题

解决：不要用 root 跑 Node.js 应用。创建一个普通用户：

bash
# 创建应用用户
useradd -m appuser
# 切到普通用户运行
su - appuser -c "cd /app && npm run start"

总结 ​

这 10 个坑覆盖了 90% 的国内 AI Agent 部署问题。核心思路就三个：

  1. 镜像绕过去 —— GitHub/Docker/npm 都有国内镜像
  2. 代理配通 —— API 调用必须走代理或中转
  3. 环境检查三连 —— node --version / pip list / .env 是否存在

更多详细方案，参考分类教程：