mirror of https://github.com/patdelphi/suanming.git synced 2026-02-27 21:23:12 +08:00

Files

patdelphi b5011988fb docs: 更新系统文档以反映Volume挂载路径修复

- 更新KOYEB_DEPLOYMENT.md部署指南
  * 修正Volume挂载路径从/app/data到/workspace/data
  * 更新环境变量配置示例，添加DB_PATH等新变量
  * 完善故障排除指南，添加日志验证方法
  * 新增Volume挂载路径问题专门说明章节
  * 更新数据备份路径和相关命令

- 更新CHANGELOG.md版本记录
  * 添加v3.1.1版本更新记录
  * 详细记录Koyeb Volume挂载路径修复
  * 记录数据库配置优化和环境检测改进
  * 记录文档更新和部署指南完善

- 文档改进内容
  * 明确不同环境的数据库路径配置策略
  * 添加环境检测和自动适配机制说明
  * 提供详细的故障排除和验证方法
  * 确保部署文档与实际配置完全一致

2025-08-23 00:18:27 +08:00

5.3 KiB

Raw Permalink Blame History

Koyeb 部署指南

本指南将帮助您将神机阁项目部署到 Koyeb 平台。

🚀 部署步骤

1. 准备工作

确保您的代码已推送到 GitHub 仓库的 master 分支。

2. 注册 Koyeb 账号

访问 Koyeb官网
注册免费账号
验证邮箱

3. 创建新应用

登录 Koyeb 控制台
点击 "Create App"
选择 "GitHub" 作为部署源
授权 Koyeb 访问您的 GitHub 仓库
选择您的项目仓库
选择 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 确保应用使用生产环境配置

持久化存储

在 "Volumes" 部分添加存储卷
Name: sqlite-data
Mount Path: /workspace/data ⚠️ 重要: 必须使用 /workspace/data，这是 Koyeb 的实际挂载路径
Size: 1GB

注意: Koyeb 实际将 Volume 挂载到 /workspace/data 而不是 /app/data。应用已自动检测并适配此路径。

5. 部署应用

检查所有配置
点击 "Deploy"
等待部署完成（通常需要 3-5 分钟）

6. 获取应用URL

部署完成后，Koyeb 会提供一个类似这样的URL：

https://your-app-name-your-org.koyeb.app

7. 更新前端配置

复制您的 Koyeb 应用 URL
更新 src/lib/localApi.ts 中的 API URL：

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');

提交并推送更改

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 控制台中：

进入您的应用
点击 "Logs" 标签
查看实时日志输出

📊 监控和维护

健康检查

Koyeb 会自动监控您的应用健康状态：

端点: /api/health
检查间隔: 10秒
超时时间: 5秒

数据备份

定期备份您的 SQLite 数据库：

在 Koyeb 控制台中访问您的应用
使用 "Terminal" 功能连接到容器
复制 /workspace/data/numerology.db 文件
使用命令：cp /workspace/data/numerology.db /tmp/backup-$(date +%Y%m%d).db

扩展和升级

如需更多资源：

在 Koyeb 控制台中选择更大的实例类型
增加存储卷大小
配置自动扩展规则

💰 费用说明

免费套餐包含：

512MB RAM
100GB 带宽/月
1个应用
基础支持

注意: 超出免费额度后会产生费用，请监控使用情况。

🔗 有用链接

⚠️ 重要更新：Volume 挂载路径修复

2024年更新: 经过实际部署测试发现，Koyeb 将 Volume 挂载到 /workspace/data 而不是文档中的 /app/data。

问题症状

如果您看到以下日志输出，说明路径配置有问题：

🗄️ 数据库路径: /workspace/numerology.db  ❌ 错误
🌍 运行环境: development                  ❌ 错误
🏢 Koyeb环境: No                          ❌ 错误

正确的日志输出

修复后应该看到：

🗄️ 数据库路径: /workspace/data/numerology.db  ✅ 正确
🌍 运行环境: development                      ✅ 正常
🏢 Koyeb环境: Yes                            ✅ 正确
📁 数据库目录已存在: /workspace/data          ✅ 正确

解决方案

应用已自动检测 Koyeb 环境并使用正确路径。确保：

Volume 挂载路径设置为 /workspace/data
环境变量 DB_PATH=/workspace/data/numerology.db
应用会自动检测并适配正确路径

🆘 获取帮助

如果遇到问题：

查看 Koyeb 官方文档
检查应用日志
联系 Koyeb 支持团队
在项目 GitHub 仓库中创建 Issue

部署成功后，您的神机阁应用就可以在全球范围内访问了！ 🎉

5.3 KiB Raw Permalink Blame History Unescape Escape