华夏家谱 (HuaXiaJiaPu) - 中国家族树管理系统

现代化的中国家族树管理系统，支持多用户协作、权限管理、数据导入导出等功能。

技术栈

• 前端: Next.js 16, React 19, TypeScript, TailwindCSS
• 后端: Next.js API Routes, Prisma ORM
• 数据库: PostgreSQL
• 认证: NextAuth.js
• UI组件: shadcn/ui, Radix UI
• 图标: Lucide Icons

功能特性

核心功能

• ✅ 家族树可视化展示
• ✅ 成员信息管理（基本信息、照片、故事）
• ✅ 多家族树支持
• ✅ 用户认证与授权
• ✅ 协作者管理（所有者、编辑者、查看者）
• ✅ 操作日志记录
• ✅ GEDCOM 格式导入导出
• ✅ 数据备份与恢复

权限系统

• 所有者 (OWNER): 完全控制权限
• 编辑者 (EDITOR): 可以编辑成员信息
• 查看者 (VIEWER): 只读访问权限

快速开始

环境要求

• Node.js 18+
• PostgreSQL 14+
• pnpm (推荐)

安装

# 克隆项目
git clone <repository-url>
cd chinese-family-tree

# 安装依赖
pnpm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库连接和认证密钥

# 初始化数据库
pnpm prisma generate
pnpm prisma db push

# 运行开发服务器
pnpm dev

访问 http://localhost:3000

生产构建

# 构建
pnpm build

# 启动生产服务器
pnpm start

生产部署

一键部署脚本

项目提供了自动化部署脚本，支持一键部署到远程服务器：

# 1. 编辑 deploy.sh 配置服务器信息
# 2. 运行部署脚本
./deploy.sh

部署脚本会自动完成：

• SSH密钥配置
• 服务器环境检查
• 本地构建项目
• 文件上传
• 数据库初始化
• PM2进程管理

服务器要求

• 操作系统：Ubuntu 20.04+ / CentOS 7+ / Debian 10+
• 内存：至少 2GB RAM
• 磁盘：至少 10GB 可用空间
• PostgreSQL 14+

常见问题

重定向循环问题 (ERR_TOO_MANY_REDIRECTS)

如果遇到重定向循环错误：

1. 检查 NEXTAUTH_URL 是否与实际访问URL一致
2. 清除浏览器缓存和Cookie
3. 重启应用：ssh user@server 'pm2 restart chinese-family-tree'

其他问题

• 查看应用日志：ssh user@server 'pm2 logs chinese-family-tree'
• 检查数据库连接：npx prisma db pull
• 重启应用：ssh user@server 'pm2 restart chinese-family-tree'

环境变量

创建 .env 文件并配置以下变量：

# 数据库
DATABASE_URL="postgresql://user:password@localhost:5432/family_tree"

# NextAuth
# ⚠️ 重要: NEXTAUTH_URL 必须与实际访问URL完全一致
# 开发环境:
NEXTAUTH_URL="http://localhost:3000"
# 生产环境示例:
# NEXTAUTH_URL="http://your-server-ip:port"
# NEXTAUTH_URL="https://your-domain.com"

NEXTAUTH_SECRET="your-secret-key-here"

# 邮箱服务器配置（用于发送邀请邮件）
SMTP_HOST="smtp.163.com"
SMTP_PORT="465"
SMTP_USER="cftservice@163.com"
SMTP_PASS="your-smtp-password"
SMTP_FROM="中华家谱 <cftservice@163.com>"

# 可选：OAuth 提供商
# GOOGLE_CLIENT_ID=""
# GOOGLE_CLIENT_SECRET=""

⚠️ 重要提示: NEXTAUTH_URL 必须与实际访问URL完全一致，否则会导致重定向循环问题 (ERR_TOO_MANY_REDIRECTS)

项目结构

├── app/                    # Next.js App Router
│   ├── api/               # API 路由
│   ├── auth/              # 认证页面
│   ├── members/           # 成员管理
│   ├── settings/          # 设置页面
│   └── tree/              # 家族树可视化
├── components/            # React 组件
│   ├── ui/               # UI 基础组件
│   ├── members/          # 成员相关组件
│   └── settings/         # 设置相关组件
├── context/              # React Context
├── lib/                  # 工具函数
├── prisma/               # 数据库 Schema
└── types/                # TypeScript 类型定义

数据库 Schema

主要数据表：

• User: 用户信息
• FamilyTree: 家族树
• FamilyMember: 家族成员
• TreeCollaborator: 协作者
• ActivityLog: 操作日志

API 路由

认证

• POST /api/auth/register - 用户注册
• POST /api/auth/signin - 用户登录

家族树

• GET /api/trees - 获取家族树列表
• POST /api/trees - 创建家族树
• GET /api/trees/[treeId] - 获取单个家族树
• PUT /api/trees/[treeId] - 更新家族树
• DELETE /api/trees/[treeId] - 删除家族树

成员

• GET /api/trees/[treeId]/members - 获取成员列表
• POST /api/trees/[treeId]/members - 创建成员
• PUT /api/trees/[treeId]/members/[memberId] - 更新成员
• DELETE /api/trees/[treeId]/members/[memberId] - 删除成员

协作者

• GET /api/trees/[treeId]/collaborators - 获取协作者列表
• POST /api/trees/[treeId]/collaborators - 添加协作者
• DELETE /api/trees/[treeId]/collaborators - 移除协作者

操作日志

• GET /api/trees/[treeId]/activity-logs - 获取操作日志
• DELETE /api/trees/[treeId]/activity-logs - 清空操作日志（仅所有者）

开发指南

代码规范

• 使用 TypeScript 严格模式
• 遵循 ESLint 规则
• 使用 Prettier 格式化代码

提交规范

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式调整
• refactor: 代码重构
• test: 测试相关
• chore: 构建/工具相关

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！

lsof -ti:3000 | xargs kill -9 2>/dev/null; echo "端口已清理"

pnpm dev