mirror of
https://github.com/patdelphi/suanming.git
synced 2026-02-28 05:33:11 +08:00
b5011988fb
- 更新KOYEB_DEPLOYMENT.md部署指南 * 修正Volume挂载路径从/app/data到/workspace/data * 更新环境变量配置示例，添加DB_PATH等新变量 * 完善故障排除指南，添加日志验证方法 * 新增Volume挂载路径问题专门说明章节 * 更新数据备份路径和相关命令 - 更新CHANGELOG.md版本记录 * 添加v3.1.1版本更新记录 * 详细记录Koyeb Volume挂载路径修复 * 记录数据库配置优化和环境检测改进 * 记录文档更新和部署指南完善 - 文档改进内容 * 明确不同环境的数据库路径配置策略 * 添加环境检测和自动适配机制说明 * 提供详细的故障排除和验证方法 * 确保部署文档与实际配置完全一致
199 lines
5.3 KiB
Markdown
199 lines
5.3 KiB
Markdown
# Koyeb 部署指南
|
||
|
||
本指南将帮助您将神机阁项目部署到 Koyeb 平台。
|
||
|
||
## 🚀 部署步骤
|
||
|
||
### 1. 准备工作
|
||
|
||
确保您的代码已推送到 GitHub 仓库的 `master` 分支。
|
||
|
||
### 2. 注册 Koyeb 账号
|
||
|
||
1. 访问 [Koyeb官网](https://www.koyeb.com/)
|
||
2. 注册免费账号
|
||
3. 验证邮箱
|
||
|
||
### 3. 创建新应用
|
||
|
||
1. 登录 Koyeb 控制台
|
||
2. 点击 "Create App"
|
||
3. 选择 "GitHub" 作为部署源
|
||
4. 授权 Koyeb 访问您的 GitHub 仓库
|
||
5. 选择您的项目仓库
|
||
6. 选择 `master` 分支
|
||
|
||
### 4. 配置部署设置
|
||
|
||
#### 基本设置
|
||
- **App Name**: `suanming-app`（或您喜欢的名称）
|
||
- **Service Name**: `suanming-backend`
|
||
- **Instance Type**: `Nano` (免费套餐)
|
||
- **Port**: `8000`
|
||
|
||
#### 构建设置
|
||
- **Build Command**: `npm ci`
|
||
- **Run Command**: `npm start`
|
||
|
||
#### 环境变量
|
||
在 Koyeb 控制台中添加以下环境变量：
|
||
|
||
```
|
||
NODE_ENV=production
|
||
PORT=8000
|
||
DB_PATH=/workspace/data/numerology.db
|
||
JWT_SECRET=xVtKLcdGpYdtoEjEBE9hFTJgBCJrEIu9AjXtAJMtwTU=
|
||
JWT_EXPIRES_IN=7d
|
||
LOG_LEVEL=info
|
||
```
|
||
|
||
**重要**:
|
||
- `DB_PATH` 必须设置为 `/workspace/data/numerology.db` 以匹配 Koyeb 的实际挂载路径
|
||
- `JWT_SECRET` 已设置为安全的随机字符串，生产环境可继续使用
|
||
- `NODE_ENV=production` 确保应用使用生产环境配置
|
||
|
||
#### 持久化存储
|
||
1. 在 "Volumes" 部分添加存储卷
|
||
2. **Name**: `sqlite-data`
|
||
3. **Mount Path**: `/workspace/data` ⚠️ **重要**: 必须使用 `/workspace/data`，这是 Koyeb 的实际挂载路径
|
||
4. **Size**: `1GB`
|
||
|
||
**注意**: Koyeb 实际将 Volume 挂载到 `/workspace/data` 而不是 `/app/data`。应用已自动检测并适配此路径。
|
||
|
||
### 5. 部署应用
|
||
|
||
1. 检查所有配置
|
||
2. 点击 "Deploy"
|
||
3. 等待部署完成（通常需要 3-5 分钟）
|
||
|
||
### 6. 获取应用URL
|
||
|
||
部署完成后，Koyeb 会提供一个类似这样的URL：
|
||
```
|
||
https://your-app-name-your-org.koyeb.app
|
||
```
|
||
|
||
### 7. 更新前端配置
|
||
|
||
1. 复制您的 Koyeb 应用 URL
|
||
2. 更新 `src/lib/localApi.ts` 中的 API URL：
|
||
|
||
```typescript
|
||
const API_BASE_URL = import.meta.env.VITE_API_BASE_URL ||
|
||
(import.meta.env.PROD ? 'https://your-actual-app-url.koyeb.app/api' : 'http://localhost:3001/api');
|
||
```
|
||
|
||
3. 提交并推送更改
|
||
|
||
### 8. 验证部署
|
||
|
||
访问以下端点验证部署是否成功：
|
||
|
||
- **健康检查**: `https://your-app-url.koyeb.app/api/health`
|
||
- **API根路径**: `https://your-app-url.koyeb.app/api`
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 常见问题
|
||
|
||
#### 1. 应用启动失败
|
||
- 检查环境变量是否正确设置
|
||
- 查看 Koyeb 日志中的错误信息
|
||
- 确保 `package.json` 中的 `start` 脚本正确
|
||
|
||
#### 2. 数据库连接问题
|
||
- 确保持久化存储卷已正确配置
|
||
- **重要**: 检查 `/workspace/data` 目录权限（不是 `/app/data`）
|
||
- 查看数据库初始化日志
|
||
- 确认日志中显示：`🗄️ 数据库路径: /workspace/data/numerology.db`
|
||
- 确认日志中显示：`🏢 Koyeb环境: Yes`
|
||
|
||
#### 3. CORS 错误
|
||
- 在服务器配置中添加您的前端域名到 CORS 白名单
|
||
- 更新 `server/index.cjs` 中的 CORS 配置
|
||
|
||
### 查看日志
|
||
|
||
在 Koyeb 控制台中：
|
||
1. 进入您的应用
|
||
2. 点击 "Logs" 标签
|
||
3. 查看实时日志输出
|
||
|
||
## 📊 监控和维护
|
||
|
||
### 健康检查
|
||
|
||
Koyeb 会自动监控您的应用健康状态：
|
||
- **端点**: `/api/health`
|
||
- **检查间隔**: 10秒
|
||
- **超时时间**: 5秒
|
||
|
||
### 数据备份
|
||
|
||
定期备份您的 SQLite 数据库：
|
||
1. 在 Koyeb 控制台中访问您的应用
|
||
2. 使用 "Terminal" 功能连接到容器
|
||
3. 复制 `/workspace/data/numerology.db` 文件
|
||
4. 使用命令：`cp /workspace/data/numerology.db /tmp/backup-$(date +%Y%m%d).db`
|
||
|
||
### 扩展和升级
|
||
|
||
如需更多资源：
|
||
1. 在 Koyeb 控制台中选择更大的实例类型
|
||
2. 增加存储卷大小
|
||
3. 配置自动扩展规则
|
||
|
||
## 💰 费用说明
|
||
|
||
**免费套餐包含**：
|
||
- 512MB RAM
|
||
- 100GB 带宽/月
|
||
- 1个应用
|
||
- 基础支持
|
||
|
||
**注意**: 超出免费额度后会产生费用，请监控使用情况。
|
||
|
||
## 🔗 有用链接
|
||
|
||
- [Koyeb 文档](https://www.koyeb.com/docs)
|
||
- [Koyeb 定价](https://www.koyeb.com/pricing)
|
||
- [Koyeb 支持](https://www.koyeb.com/support)
|
||
|
||
## ⚠️ 重要更新：Volume 挂载路径修复
|
||
|
||
**2024年更新**: 经过实际部署测试发现，Koyeb 将 Volume 挂载到 `/workspace/data` 而不是文档中的 `/app/data`。
|
||
|
||
### 问题症状
|
||
如果您看到以下日志输出，说明路径配置有问题：
|
||
```
|
||
🗄️ 数据库路径: /workspace/numerology.db ❌ 错误
|
||
🌍 运行环境: development ❌ 错误
|
||
🏢 Koyeb环境: No ❌ 错误
|
||
```
|
||
|
||
### 正确的日志输出
|
||
修复后应该看到：
|
||
```
|
||
🗄️ 数据库路径: /workspace/data/numerology.db ✅ 正确
|
||
🌍 运行环境: development ✅ 正常
|
||
🏢 Koyeb环境: Yes ✅ 正确
|
||
📁 数据库目录已存在: /workspace/data ✅ 正确
|
||
```
|
||
|
||
### 解决方案
|
||
应用已自动检测 Koyeb 环境并使用正确路径。确保：
|
||
1. Volume 挂载路径设置为 `/workspace/data`
|
||
2. 环境变量 `DB_PATH=/workspace/data/numerology.db`
|
||
3. 应用会自动检测并适配正确路径
|
||
|
||
## 🆘 获取帮助
|
||
|
||
如果遇到问题：
|
||
1. 查看 Koyeb 官方文档
|
||
2. 检查应用日志
|
||
3. 联系 Koyeb 支持团队
|
||
4. 在项目 GitHub 仓库中创建 Issue
|
||
|
||
---
|
||
|
||
**部署成功后，您的神机阁应用就可以在全球范围内访问了！** 🎉 |