Galzy

面向中文玩家的现代化 Galgame 资源平台 —— 收录汉化版与翻译版 Galgame，提供发现、下载、攻略与社区功能，一站整合。

• 📖 全文搜索 — 基于 Meilisearch，覆盖游戏、标签、制作商三个索引，针对中文优化，毫秒级响应
• 🔄 VNDB 数据同步 — 通过 VNDB API（Kana）全量/增量同步视觉小说、标签、发行版、制作商数据，带分布式锁与进度跟踪，同步后自动清除 CDN 缓存
• 🌐 KunGal 目录同步 — 对接 NextMoe·未萌开放 API，以 VNDB ID 为锚点同步目录数据
• 🔐 多种登录方式 — 邮箱/密码、邮箱 OTP，以及 GitHub、Discord、Twitter、Kungal、Linux.do 等 OAuth 登录，中文本地化
• 🏷️ 标签系统 — VNDB 标签中文本地化、游戏-标签关联、批量导入导出
• 💬 评论与社区 — 嵌套评论、管理员审核（置顶/状态）、回复邮件通知；论坛话题（发布、点赞、收藏）
• 📝 攻略模块 — Markdown 文章 CRUD（攻略指南、博客、教程），游戏-文章关联
• 📥 游戏下载 — 基于 Cloudreve 的签名直链下载，文件树浏览与数据同步
• 📊 自建访问统计 — 页面访问事件追踪（galrc_event_views），热门游戏/标签排行，替代第三方统计
• 🗂️ 任务队列 — 基于 @stacksjs/bun-queue 的后台任务队列，管理端可查询任务状态、日志并手动入队
• 🔧 管理后台 — 用户管理、评论审核、文章管理、合集管理、搜索索引管理
• 📄 OpenAPI 文档 — 由 @elysia/openapi 自动生成 Swagger 文档
• 📡 OpenTelemetry — 分布式链路追踪（生产环境按需开启）
• 🎨 现代前端 — React 19 + TanStack 全家桶 + Tailwind CSS v4 + shadcn/ui，深色/浅色主题，React Compiler 加持
• 🐳 容器化交付 — Docker 多阶段构建生成 distroless 精简镜像，GitHub Actions 自动构建推送 ghcr.io 并通过 webhook 触发部署

浏览器 ──▶ TanStack Start SSR（端口 3000）
                │  createServerFn（BFF 层）
                │  Eden Treaty（类型安全 RPC）
                ▼
         ElysiaJS API（端口 3001）
                │
    ┌───────────┼───────────┐
    ▼           ▼           ▼
PostgreSQL    Redis     Meilisearch
 (Drizzle)  （缓存/锁）   （搜索）

• 浏览器 → SSR Server Functions → Eden Treaty → Elysia API → Drizzle ORM → PostgreSQL
• Redis 提供缓存、分布式锁与任务队列底层存储；开发模式下默认不启用（直查 DB），可设 REDIS_ENABLED=true 强制开启
• 后台任务（搜索索引重建、Cloudreve 同步等）经 bun-queue 异步执行，管理端可通过 /tasks 查询进度与日志

galzy/
├── apps/
│   ├── api/                          # ElysiaJS 后端（端口 3001）
│   │   ├── src/
│   │   │   ├── index.ts              # 应用入口，挂载全部模块
│   │   │   ├── modules/              # 19 个业务模块（三体结构）
│   │   │   ├── db/                   # Drizzle schema + 客户端 + 启动自动迁移
│   │   │   └── libs/                 # redis / meilisearch / queue / vndb-api / cloudreve / ...
│   │   ├── drizzle/                  # 迁移 SQL（Drizzle Kit 生成）
│   │   ├── Dockerfile                # 多阶段 distroless 构建
│   │   └── .env.example              # 环境变量模板
│   └── web-tanstack/                 # TanStack Start 前端（端口 3000）
│       ├── src/
│       │   ├── routes/               # 基于文件的约定式路由
│       │   ├── server/               # Server Functions（BFF 层，按领域划分）
│       │   ├── components/           # shadcn/ui + 自定义组件
│       │   ├── stores/               # TanStack Store / Zustand（客户端 UI 状态）
│       │   ├── hooks/                # 自定义 React Hooks
│       │   └── lib/                  # cn() / cookiePass() / elysiaErrorF() 等工具
│       └── Dockerfile
├── packages/
│   ├── libs/                         # Eden Treaty 类型安全客户端（含 Cookie 转发）
│   └── config/typescript/            # 共享 tsconfig（路径别名 @api / @web / @libs）
├── scripts/
│   ├── run.ts                        # 工作空间并发命令执行器
│   ├── docker.ts                     # Docker 构建编排
│   └── pakadd.ts                     # 按工作空间添加依赖
├── .github/workflows/build-deploy.yml # CI：Docker 构建 → ghcr.io → webhook 部署
├── biome.json                        # Biome 格式化 / Lint 配置
├── renovate.json                     # 自动依赖更新配置
└── AGENTS.md                         # AI 编程助手项目指南

cp apps/api/.env.example apps/api/.env

核心变量（完整列表见 apps/api/.env.example）：

# 1. 安装所有工作空间依赖
bun install

# 2. 应用数据库迁移（首次启动也会自动迁移空库）
bun --cwd apps/api db:up

# 3. 启动开发服务器（并行运行所有应用：API 3001 + Web 3000）
bun run dev

也可单独启动：

bun --cwd apps/api dev            # 仅 API（watch 模式）
bun --cwd apps/web-tanstack dev   # 仅 Web（Vite dev server）

curl http://localhost:3001/health
# {"ok":true}

重要： 本项目采用迁移优先工作流，禁止使用 db:push（它会对比整个数据库并可能提示删除非应用表）。

# 1. 根据 schema 变更生成迁移 SQL
bun --cwd apps/api db:generate

# 2. 应用挂起的迁移（bun-sql migrator，幂等）
bun --cwd apps/api db:up

# 3. 校验 schema 与数据库一致性
bun --cwd apps/api db:check

补充说明：

• API 启动时自动检测：全新数据库会自动完成首次迁移；已有表但无迁移日志的库会跳过并告警
• 不要使用 drizzle-kit migrate（已知问题：无限挂起）；db:up 使用与启动自动迁移相同的实现
• 可视化管理：bun --cwd apps/api db:studio

多阶段构建，最终产物为 gcr.io/distroless/base 之上的单二进制运行时：

# 一键构建全部镜像
bun run docker

# 或分别构建
bun --cwd apps/api docker
bun --cwd apps/web-tanstack docker

镜像特性：

• API：bun build --compile 编译为单二进制
• Web：Vite 构建产物嵌入单二进制
• 最小攻击面，无 shell、无包管理器

推送至 main 分支后，build-deploy.yml 按变更路径自动选择构建目标（apps/api/** 或 apps/web-tanstack/**），构建 Docker 镜像推送至 ghcr.io，再通过 webhook 通知生产环境拉取部署。

• TypeScript strict 全项目启用；module: Preserve + bundler 解析，Bun 直接运行 TS，无编译步骤
• Biome 格式化：2 空格缩进、单引号、尾逗号、80 字符行宽、LF 换行
• Lint：API 用 Biome，Web 用 oxlint；提交前请跑 bun run lint

每个业务模块位于 apps/api/src/modules/<name>/，统一遵循三层结构：

modules/<name>/
├── index.ts    # Elysia 插件 —— 路由、中间件、auth/isAdmin 宏
├── model.ts    # TypeBox 模式 —— 请求校验与响应类型
└── service.ts  # 业务逻辑 —— Drizzle 查询、Redis 缓存、外部 API

校验一律使用 Elysia 的 t（TypeBox），不使用 Zod。

• Server Functions 必须使用 .validator()（Zod）校验输入；每次 Eden 调用必须将 error 传给 elysiaErrorF()（401 重定向登录页）
• 登录态请求通过 cookiePass() 转发 Cookie
• 路由使用 loader + loaderDeps + validateSearch（Zod）模式；管理页用 beforeLoad 守卫
• UI 组件基于 shadcn/ui（@base-ui/react），变体用 cva，类名合并用 cn()

详细约定参见 AGENTS.md。

1. Fork 本仓库
2. 创建功能分支：feat/<功能> 或 fix/<修复>
3. 遵循上述代码规范（API 三体结构 / 前端路由约定 / Biome 格式化）
4. 运行 bun run lint && bun run typecheck 确保质量
5. 提交 Pull Request，附清晰的修改说明

本项目以 MIT 许可证开源。

用 ❤️ 和 Bun 构建 · 让 Galgame 文化更易触及