本指南用于本地开发目的。对于生产部署，请参阅部署 Kodus 指南。
先决条件
- Node.js（LTS 版本）
- Yarn 或 NPM
- Docker
- Kodus API 正在运行（请参阅编排器设置）
- LLM API 密钥
运行项目
- 自动设置（推荐）
- 手动设置
要进行快速自动设置，请使用我们的设置脚本：此脚本将自动：运行脚本后，您只需要：
- ✅ 检查
.env.example是否存在 - ✅ 生成安全的 NextAuth 密钥
- ✅ 处理与 API 的 JWT 密钥同步
- ✅ 创建和配置
.env文件 - ✅ 提供清晰的后续步骤
JWT 密钥选项：
- 选项 1：使用现有的 API JWT 密钥（如果已配置 API，则推荐）
- 选项 2：生成新的 JWT 密钥（复制到 API .env 文件）
- 选项 3：暂时跳过 JWT 设置
开发工作流程
基本本地开发
- 启动服务：
yarn docker:start - 访问 Web 应用：
http://localhost:3000 - 监控日志：
yarn docker:logs
与 API 集成的开发
如果您正在使用 Kodus API 进行开发：- 确保 API 正在运行：API 应可在
http://localhost:3001访问 - 验证 JWT 密钥匹配：Web 和 API 必须使用相同的 JWT 密钥
- 测试身份验证：尝试登录以验证连接
服务端点
访问应用程序：- 开发：
http://localhost:3000 - API（外部）：
http://localhost:3001
故障排除
常见问题
身份验证不工作：- 验证 Web 和 API 之间的 JWT 密钥是否匹配
- 检查 API 是否正在运行且可访问
- 确保
NEXT_PUBLIC_API_URL正确
- 清除 Docker 缓存：
docker system prune -a - 重建：
yarn docker:build --no-cache
- 验证项目根目录中存在
.env文件 - 检查
.env文件中的语法错误 - 在
.env更改后重启 Docker 服务
- 验证 API 是否在端口 3001 上运行
- 检查容器之间的网络连接
- 验证 API 健康端点：
http://localhost:3001/health
获取帮助
如果遇到问题：- 检查日志：
yarn docker:logs - 验证 API 状态：确保 Kodus API 正在运行
- 检查环境变量：确保设置了所有必需的值
- 查看 API 设置指南 了解后端配置