TouchGAL 项目安装与配置完整指南

TouchGAL 是一个专为 Galgame 爱好者打造的一站式文化社区平台，提供论坛交流、游戏资源下载等核心服务。本文将为你详细介绍如何从零开始搭建和配置这个基于 TypeScript 的现代化 Web 项目。

快速上手：环境准备与基础运行

在开始之前，请确保你的开发环境中已经安装了以下必备软件：

• Node.js (推荐 LTS 版本)
• pnpm (高性能包管理工具)
• PostgreSQL (关系型数据库)
• Redis (内存数据存储)

第一步：获取项目代码

使用 Git 克隆项目到本地目录：

git clone https://gitcode.com/gh_mirrors/ku/kun-touchgal-next.git
cd kun-touchgal-next

第二步：环境变量配置

参考项目根目录下的 .env.example 文件，创建你自己的 .env 配置文件。以下是基础配置示例：

# 数据库连接配置
KUN_DATABASE_URL="postgresql://username:password@localhost:5432/touchgal?schema=public"

# 网站基础配置
KUN_VISUAL_NOVEL_SITE_URL="https://www.touchgal.io"
NEXT_PUBLIC_KUN_PATCH_ADDRESS_DEV="http://127.0.0.1:3000"

# Redis 配置
REDIS_HOST="127.0.0.1"
REDIS_PORT="6379"

# JWT 安全配置
JWT_ISS="touchgal"
JWT_AUD="touchgal_admin"
JWT_SECRET="your_secure_secret_key"

# 运行环境
NODE_ENV="development"

第三步：数据库初始化

使用 Prisma 进行数据库迁移和架构生成：

# 生成 Prisma 客户端
pnpm prisma:generate

# 创建数据库迁移
pnpm prisma:migrate dev --create-only

第四步：安装依赖并运行

安装项目所需的所有依赖包：

pnpm install

启动开发服务器：

pnpm dev

现在打开浏览器访问 http://localhost:3000，你应该能够看到 TouchGAL 项目正常运行。

深度配置：核心功能调优

数据库优化配置

为了获得更好的数据库性能，建议在 PostgreSQL 中针对 TouchGAL 进行以下优化：

-- 为常用查询字段创建索引
CREATE INDEX idx_patch_created_at ON patch(created_at);
CREATE INDEX idx_user_email ON user(email);

Redis 缓存策略

在 config/redis.ts 中配置 Redis 连接池和超时设置，确保高并发场景下的稳定性。

邮件服务集成

如果需要启用邮件通知功能，在 .env 中添加邮件服务配置：

KUN_VISUAL_NOVEL_EMAIL_FROM="TouchGAL 通知系统"
KUN_VISUAL_NOVEL_EMAIL_HOST="your-smtp-server.com"
KUN_VISUAL_NOVEL_EMAIL_PORT="587"
KUN_VISUAL_NOVEL_EMAIL_ACCOUNT="[e-mail]"
KUN_VISUAL_NOVEL_EMAIL_PASSWORD="your_email_password"

进阶优化：性能与安全

图片存储优化

TouchGAL 支持多种图片格式，建议配置 CDN 加速静态资源访问：

安全加固措施

1. JWT 密钥保护：确保 JWT_SECRET 使用强密码并定期更换
2. 数据库连接加密：启用 PostgreSQL 的 SSL 连接
3. API 速率限制：在 middleware.ts 中配置请求频率限制

性能监控配置

集成性能监控工具，实时跟踪应用运行状态：

# 安装监控依赖
pnpm add @opentelemetry/api @opentelemetry/sdk-node

实用小贴士与常见问题

开发调试技巧

• 使用 pnpm dev --turbo 启用 TurboPack 加速开发编译
• 在 VSCode 中安装 Prisma 扩展获得更好的数据库开发体验
• 利用 store/ 目录下的状态管理工具进行调试

常见问题解决

Q: 数据库连接失败怎么办？ A: 检查 PostgreSQL 服务是否启动，以及 .env 中的数据库连接字符串是否正确。

Q: 图片上传功能异常？ A: 确认 S3 存储配置或本地存储权限设置正确。

Q: 邮件发送失败？ A: 验证 SMTP 服务器配置和端口是否被防火墙阻挡。

生产环境部署建议

1. 使用 PM2 或 Docker 进行进程管理
2. 配置 Nginx 反向代理和 SSL 证书
3. 设置定期数据库备份任务
4. 启用日志轮转和监控告警

结语

通过本指南，你应该已经成功搭建了 TouchGAL Galgame 社区平台。这个基于 TypeScript 和 Next.js 的项目为 Galgame 爱好者提供了一个功能完备的交流平台。如果在部署过程中遇到任何问题，建议查阅项目文档或参与社区讨论。

记住，良好的 Galgame 社区搭建不仅需要技术实现，更需要理解社区文化和用户需求。祝你的 TouchGAL 项目运行顺利！