部署文档

搭建说明

从环境准备到上线部署的完整指南

开始前请确保您的开发环境满足以下要求。

$ Node.js >= 18.0.0
$ npm >= 9.0.0 或 pnpm >= 8.0.0
$ Python >= 3.9（如需Python SDK）
$ Git >= 2.30.0

推荐使用 nvm 管理 Node.js 版本，确保版本可灵活切换。

全局安装小白AI网站系统命令行工具。

$ npm install -g xiaobai-ai-cli
$ xiaobai-ai --version

安装完成后可使用 xiaobai-ai --help 查看所有可用命令。

创建新的AI应用项目，选择模板和配置。

$ xiaobai-ai init my-ai-app
$ cd my-ai-app
$ npm install

初始化时会引导您选择项目模板（对话应用/知识库/数据分析）和默认模型。

在项目根目录创建 .env 文件，配置必要的密钥和连接信息。

$ MODEL_API_KEY=your_model_api_key
$ DB_URL=postgresql://user:pass@localhost:5432/db
$ PORT=3000
$ LOG_LEVEL=info

API Key 可在控制台的「秘钥管理」中获取，请勿将 .env 文件提交到版本库。

启动本地开发服务器进行调试和验证。

$ npm run dev
# 服务将启动在 http://localhost:3000

开发模式下支持热更新，修改代码后自动重新加载。

使用Docker容器化部署，确保环境一致性。

$ docker build -t my-ai-app .
$ docker run -p 3000:3000 --env-file .env my-ai-app

项目内置 Dockerfile 和 docker-compose.yml，支持一键容器化部署。

将应用部署到云端，正式对外提供服务。

$ xiaobai-ai deploy --platform cloud
# 或部署到指定云平台
$ xiaobai-ai deploy --platform aliyun

部署前请确保已配置正确的环境变量和域名信息。

常见问题

尝试使用 sudo npm install -g xiaobai-ai-cli（macOS/Linux），或使用 npx xiaobai-ai 临时执行。推荐使用 nvm 管理 Node.js 以避免权限问题。

在 .env 文件中修改 MODEL_API_KEY 对应的模型密钥，或在代码中通过 client.setModel() 动态切换。支持多模型并行配置。

检查端口映射是否正确（-p 3000:3000），确认容器内服务已正常启动（docker logs查看日志），检查防火墙和安全组设置。

运行 npm update -g xiaobai-ai-cli 更新CLI工具，项目内运行 npm update xiaobai-ai-core 更新核心库。建议查看更新日志了解Breaking Changes。