# 🐦 呆鸟修仙游戏 - 部署指南
## 📦 部署方式
本项目使用 **Coze CLI** 进行部署，支持开发环境和生产环境两种模式。
### 前置要求
- Node.js 24+
- pnpm 包管理器
- Coze CLI（已内置在开发环境）
---
## 🚀 快速部署
### 1. 开发环境部署
```bash
# 进入项目目录
cd /workspace/projects/
# 安装依赖
pnpm install
# 启动开发服务器（端口 5000）
pnpm run dev
```
### 2. 生产环境部署
```bash
# 构建项目
pnpm run build
# 启动生产服务器
pnpm run start
```
### 3. 使用 Coze CLI
```bash
# 启动开发环境（自动运行 .coze 配置）
coze dev
# 构建生产版本
coze build
# 启动生产环境
coze start
```
---
## ⚙️ 环境变量配置
### 本地开发
项目使用 **coze-coding-dev-sdk** 管理数据库和集成服务，**无需手动配置环境变量**。
### 生产部署
如果部署到生产环境，确保以下服务可用：
| 服务 | 状态 | 说明 |
|------|------|------|
| PostgreSQL | ✅ 已配置 | 通过 coze-coding-dev-sdk 自动连接 |
| 对象存储 (S3) | ✅ 已配置 | 通过 coze-coding-dev-sdk 自动连接 |
---
## 🔧 数据库配置
### 数据库 Schema
项目使用 Drizzle ORM + PostgreSQL，主要数据表：
```sql
-- 用户表
CREATE TABLE users (
id TEXT PRIMARY KEY,
username TEXT UNIQUE NOT NULL,
password TEXT NOT NULL,
douyin_link TEXT,
invite_code TEXT UNIQUE NOT NULL,
max_level INTEGER DEFAULT 1,
max_score INTEGER DEFAULT 0,
total_games INTEGER DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW(),
updated_at TIMESTAMP DEFAULT NOW()
);
-- 好友关系表
CREATE TABLE friendships (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
friend_id TEXT NOT NULL,
status TEXT DEFAULT 'pending', -- pending, accepted
created_at TIMESTAMP DEFAULT NOW()
);
-- 游戏记录表
CREATE TABLE game_records (
id TEXT PRIMARY KEY,
user_id TEXT NOT NULL,
level INTEGER NOT NULL,
score INTEGER NOT NULL,
realm TEXT NOT NULL,
play_time INTEGER DEFAULT 0,
created_at TIMESTAMP DEFAULT NOW()
);
```
### 数据库连接
项目使用 `coze-coding-dev-sdk` 的 `getDb()` 函数自动管理数据库连接：
```typescript
import { getDb } from "coze-coding-dev-sdk";
const db = await getDb(); // 自动获取已配置的数据库连接
```
---
## 📁 项目结构
```
.
├── .coze # Coze CLI 配置文件
├── .cozeproj/ # Coze 部署脚本
│ ├── scripts/
│ │ ├── dev_build.sh # 开发环境构建
│ │ ├── dev_run.sh # 开发环境运行
│ │ ├── deploy_build.sh # 生产环境构建
│ │ └── deploy_run.sh # 生产环境运行
├── src/
│ ├── app/ # Next.js App Router
│ │ ├── api/ # API 路由
│ │ │ ├── auth/ # 认证接口
│ │ │ ├── friends/ # 好友接口
│ │ │ ├── game/ # 游戏接口
│ │ │ ├── leaderboard/ # 排行榜接口
│ │ │ └── user/ # 用户接口
│ │ ├── layout.tsx # 根布局
│ │ └── page.tsx # 主页面（游戏）
│ ├── components/ # 组件库
│ │ └── ui/ # shadcn/ui 组件
│ └── storage/
│ └── database/ # 数据库管理
│ ├── shared/ # Schema 定义
│ ├── userManager.ts
│ ├── friendshipManager.ts
│ └── gameRecordManager.ts
├── package.json
└── tsconfig.json
```
---
## 🌐 访问地址
- **开发环境**: http://localhost:5000
- **生产环境**: 根据部署平台配置的域名
---
## 🔍 验证部署
### 1. 检查服务状态
```bash
# 检查 5000 端口是否监听
curl -I http://localhost:5000
# 或使用 ss 命令
ss -tuln | grep 5000
```
### 2. 测试 API 接口
```bash
# 测试用户注册
curl -X POST http://localhost:5000/api/auth/register \
-H "Content-Type: application/json" \
-d '{"username":"test","password":"123456","confirmPassword":"123456"}'
# 测试排行榜
curl http://localhost:5000/api/leaderboard?type=global
```
### 3. 访问游戏
在浏览器中打开 `http://localhost:5000`，应能看到小鸟修仙游戏主页。
---
## 📝 常见问题
### Q1: 端口 5000 被占用怎么办？
```bash
# 查找占用 5000 端口的进程
ss -lptn 'sport = :5000'
# 杀死进程（替换 PID）
kill -9 <PID>
```
### Q2: 数据库连接失败怎么办？
确保 `coze-coding-dev-sdk` 已正确配置。该项目使用 Coze 平台的托管数据库服务，无需手动配置连接字符串。
### Q3: 如何查看日志？
开发环境日志会直接输出到控制台，生产环境日志可查看部署平台的日志服务。
### Q4: 如何更新依赖？
```bash
# 更新所有依赖
pnpm update
# 更新特定包
pnpm add <package-name>@latest
```
---
## 🔐 安全建议
1. **密码加密**：目前使用简单的 Base64 编码，生产环境建议使用 bcrypt
2. **输入验证**：所有用户输入都经过 Zod schema 验证
3. **SQL 注入防护**：使用 Drizzle ORM 的参数化查询，自动防护 SQL 注入
4. **HTTPS**：生产环境务必使用 HTTPS
---
## 📊 性能优化建议
1. **数据库索引**：为常用查询字段添加索引
2. **缓存策略**：排行榜等高频数据可以使用 Redis 缓存
3. **CDN**：静态资源（图片、字体）使用 CDN 加速
4. **代码分割**：Next.js 已自动处理路由级代码分割
---
## 🎯 下一步
- [ ] 添加更严格的密码加密（bcrypt）
- [ ] 实现 Redis 缓存层
- [ ] 添加邮件验证功能
- [ ] 实现实时排行榜（WebSocket）
- [ ] 添加游戏数据分析功能
---
## 📞 技术支持
如遇到部署问题，请检查：
1. Node.js 版本是否为 24+
2. pnpm 是否正确安装
3. 端口 5000 是否被占用
4. 数据库连接是否正常
5. 依赖是否完整安装
---
## 📄 许可证
本项目仅供学习和参考使用。