HackathonWeekly Community 代码仓库指南
HackathonWeekly Community 仓库说明、快速开始、部署与贡献
现代化的 Next.js 16 社区网站，采用 monorepo 结构。
🚀 功能特性
- Next.js 16 搭配 App Router 和 TypeScript
- 身份认证 使用 Better Auth（社交登录、魔法链接等）
- 支付系统 支持多个提供商（Stripe、WeChat Pay 等）
- 数据库 使用 Prisma 和 PostgreSQL
- 国际化 基于 next-intl
- 用户界面 采用 shadcn/ui、Radix UI 和 Tailwind CSS
- 内容管理 使用 content-collections（MDX）
- 邮件服务 支持多个提供商和 React Email
- 文件存储 兼容 S3 的存储提供商
- 日志系统 使用 Winston
- 数据分析 支持多个分析平台（Umami、Google Analytics、百度统计）
📊 数据分析
我们使用 Umami 进行网站访问统计，数据公开透明。
实时统计数据： https://cloud.umami.is/share/dEpjaVKnRNqBAkH2/hackathonweekly.com
这个链接展示了网站的实时访问数据，包括：
- 页面访问量 (PV)
- 独立访客数 (UV)
- 访问来源
- 地理位置分布
- 设备和浏览器统计
📁 项目结构
本项目采用 monorepo 结构，主要目录如下：
.
├── apps/
│ └── web/ # Next.js 16 App Router 应用
│ ├── src/app # 路由与布局
│ ├── src/modules # 业务模块
│ ├── src/features # 领域功能
│ ├── src/server # Hono API 逻辑
│ ├── content # 文档/博客等 MDX
│ └── public # 静态资源
├── packages/
│ ├── config # 共享配置与 feature flags
│ ├── lib-client # 客户端共享库
│ ├── lib-server # 服务端共享库（含 Prisma）
│ ├── lib-shared # 通用共享库
│ └── ui # 共享 UI 组件
├── scripts/ # 工具脚本🛠️ 快速开始
-
克隆仓库
git clone https://github.com/hackathonweekly/community.git cd community -
安装依赖
pnpm install -
设置环境变量
cp apps/web/.env.example apps/web/.env.local # 编辑 apps/web/.env.local 文件，填入你的配置 -
设置数据库
pnpm db:generate pnpm db:push -
启动开发服务器
pnpm dev
📚 文档
项目文档请统一查看站点：
🔐 Events Token API
如果你希望在飞书、Zapier 或自建工具中自动创建活动，可以在「账号设置 → 安全」里生成 Events Token。它是一种仅限「个人发起」活动的 API 密钥，使用方式如下：
- 生成/管理 Token：进入账户安全页的 “Events Token” 模块，点击生成或重新生成。Token 只展示一次，请立即复制。
- 请求格式：向
POST /api/events发送 JSON 负载，并在请求头添加Authorization: EventsToken <你的 token>。请求体与网页端创建活动一致，但organizationId会被忽略，所有活动都归属 Token 所在账户的个人身份。 - 速率限制：默认限制为每个 Token 每 5 分钟 60 次请求，超过会返回
429 Too Many Requests。 - 安全建议：Token 仅以哈希形式存储，可随时撤销或重新生成。建议为第三方工具准备单独的子账号，并定期旋转密钥。
简单示例：
curl -X POST https://your-domain/api/events \
-H "Authorization: EventsToken evt_xxxxx" \
-H "Content-Type: application/json" \
-d '{ "title": "API meetup", "type": "MEETUP", "isOnline": true, ... }'返回结构与普通创建一致，包含 success、data 字段，并额外提供 data.eventUrl 指向新活动的完整访问链接。若 Token 失效或权限不足，将得到相应的 401/403 错误码和提示信息。
🔧 脚本命令
pnpm dev- 启动开发服务器pnpm run build- 构建生产版本pnpm start- 启动生产服务器pnpm lint- 运行 Biome 代码检查pnpm format- 使用 Biome 格式化代码pnpm type-check- TypeScript 类型检查pnpm db:generate- 生成 Prisma 客户端pnpm db:push- 推送数据库结构pnpm db:studio- 打开 Prisma Studio
🪝 Git Hooks
本项目使用 Husky 管理 Git 钩子以维护代码质量：
- pre-commit: 提交前自动使用 Biome 格式化暂存文件
- 运行
pnpm install时会自动安装钩子 - 所有团队成员都将配置相同的钩子
新团队成员注意
克隆仓库并运行 pnpm install 后，Git 钩子将自动配置。这确保了团队间一致的代码格式化。
🌐 国际化 (i18n)
本项目使用 next-intl 支持多种语言。翻译文件位于 packages/lib-shared/src/i18n/translations/。
翻译管理
要验证和检查缺失的翻译，使用 i18n-check 命令行工具：
-
安装 i18n-check
pnpm add -D @lingual/i18n-check -
检查缺失的翻译
pnpm exec i18n-check --locales packages/lib-shared/src/i18n/translations --source en --format i18next -
添加到 package.json 脚本（可选）
{ "scripts": { "i18n:check": "i18n-check --locales packages/lib-shared/src/i18n/translations --source en --format i18next" } }
该工具将识别：
- 目标语言中缺失的翻译
- 未使用的翻译键
- 翻译间 ICU 参数使用不一致的问题
🚀 部署指南
本项目支持多种部署方式，推荐使用 Docker 进行部署。
Docker 部署（推荐）
完整的 Docker 部署文档请查看： DOCKER.md
🚀 快速部署（3分钟）
-
本地测试
# 复制环境变量模板 cp apps/web/.env.example apps/web/.env.local # 启动容器（会自动构建镜像） make up # 查看日志确认启动成功 make logs -
生产部署
# 一键发布镜像到仓库 make release TAG=v1.2.0 # 一键部署到生产环境 make deploy TAG=v1.2.0 -
紧急回滚
make rollback TAG=v1.1.9
📝 环境变量配置
| 文件 | 用途 | 位置 |
|---|---|---|
apps/web/.env.local | 本地开发和测试 | 本地机器，不提交到 Git |
apps/web/.env.production | 生产环境 | 生产服务器，包含敏感信息 |
部署
我们使用 Zeabur Docker 部署，选中 Github 仓库并且配置环境变量即可。 Postgres 数据库同样也可以通过 Zeabur 创建。
🤝 贡献指南
- Fork 本仓库
- 创建你的功能分支 (
git checkout -b feature/amazing-feature) - 提交你的更改 (
git commit -m 'Add some amazing feature') - 推送到分支 (
git push origin feature/amazing-feature) - 创建 Pull Request
📄 许可证
本项目采用 Creative Commons Attribution-NonCommercial 4.0 International License (CC BY-NC 4.0)。
🎯 许可证要点
- ✅ 允许使用：个人学习、研究、教育、开源协作
- ✅ 允许修改：可以修改和改编代码
- ✅ 允许分享：可以分享原版和修改版本
- ❌ 禁止商业使用：未经授权不得用于商业目的
- 🏷️ 需要署名：使用时必须保留版权声明
💼 商业使用
如需商业使用本项目，请联系：
- 邮箱：contact@hackathonweekly.com
- 标题：[商业使用许可申请] HackathonWeekly Community