Server

这是 Dugout 的后端服务，负责论坛数据、用户会话、管理操作和统一 API 输出。

当前实现采用以下技术栈：

• Gin 作为 HTTP 框架
• Huma 作为类型化路由注册和 OpenAPI 输出层
• PostgreSQL 作为唯一持久化数据库，启用 pgvector 和 pg_trgm
• Redis 作为必选缓存
• GORM 作为 ORM

目录结构

• cmd/：服务启动入口
• internal/config/：配置加载、默认值和校验
• internal/database/：PostgreSQL 初始化、扩展创建和表结构迁移
• internal/cache/：Redis 客户端和 JSON 缓存封装
• internal/handlers/：Huma 路由注册与 HTTP 层参数处理
• internal/repository/：数据访问层，封装业务读写、缓存失效和事务逻辑
• internal/models/：API DTO 与 GORM 模型
• internal/ratelimit/：内存限流器
• config/：本地配置样例
• Dockerfile、docker-compose.yml：容器化部署

为什么叫 repository

internal/repository 是仓储层（Repository Layer）。名字里的“仓库”不是指 Git 仓库，而是指“数据仓库/存取仓库”的抽象：

• handler 只关心 HTTP 入参、鉴权和返回值，不直接拼 SQL
• repository 统一处理数据库查询、事务、缓存读写和失效
• 业务规则可以集中放在仓储层，避免散落在路由处理函数里
• 后续如果数据库实现或缓存策略变化，handler 侧通常不需要改动

在这个项目里，repository 主要承担以下职责：

• 初始化种子数据
• 读取和更新站点配置
• 读取和维护板块、标签、帖子、举报、申诉等领域数据
• 维护登录会话和管理操作记录
• 对热点读取结果做 Redis 缓存

本地运行

前置条件

• Go 1.26+
• Docker Desktop 或兼容的 Docker 环境
• PostgreSQL 16+，建议使用 pgvector 镜像
• Redis 7+

使用 Docker Compose 启动

推荐直接使用仓库内的 Compose 编排：

docker compose up -d --build

启动后默认会提供：

• 后端服务：http://localhost:8080
• PostgreSQL：localhost:5432
• Redis：localhost:6379

本地开发启动

如果不使用 Compose，需要先准备 PostgreSQL 和 Redis，然后修改 config/config.json：

go run ./cmd

配置说明

服务读取 config/config.json，也支持通过环境变量覆盖部分值。

关键配置项

• server.port：HTTP 监听端口
• database.host：PostgreSQL 地址
• database.port：PostgreSQL 端口
• database.user：数据库用户名
• database.password：数据库密码
• database.name：数据库名
• cache.redisUrl：Redis 地址
• cache.redisPassword：Redis 密码
• cache.redisDb：Redis 数据库编号
• cache.defaultTtl：缓存默认过期时间
• security.adminToken：管理接口的管理员令牌

环境变量

• APP_CONFIG：配置文件路径
• APP_ENV：运行环境
• PORT：覆盖服务端口
• ADMIN_TOKEN：覆盖管理员令牌
• DB_HOST
• DB_PORT
• DB_USER
• DB_PASSWORD
• DB_NAME
• REDIS_URL
• REDIS_PASSWORD
• REDIS_DB

常用命令

# 运行服务
go run ./cmd

# 执行测试
go test ./...

# 格式化代码
gofmt -w ./

# 启动容器化环境
docker compose up -d --build

# 查看容器日志
docker compose logs -f server

测试策略

当前测试分为三类：

• 配置测试：验证默认值、环境变量覆盖和必填项校验
• 数据库测试：使用真实 PostgreSQL 容器验证迁移和扩展创建
• 仓储与接口测试：使用真实 PostgreSQL 容器和 Redis 替身验证业务流程、缓存和 HTTP 路由

运行 go test ./... 需要本机可访问 Docker，因为测试会自动拉起临时 PostgreSQL 容器。

API 概览

健康检查

• GET /health

基础配置

• GET /api/v1/bootstrap
• GET /api/v1/settings
• PATCH /api/v1/settings

板块与标签

• GET /api/v1/boards
• POST /api/v1/boards
• PATCH /api/v1/boards/{id}
• DELETE /api/v1/boards/{id}
• GET /api/v1/tags
• GET /api/v1/boards/{id}/tags
• POST /api/v1/tags

帖子、评论和互动

• GET /api/v1/feed
• GET /api/v1/boards/{id}/posts
• GET /api/v1/posts/search
• POST /api/v1/posts
• GET /api/v1/posts/{id}
• PATCH /api/v1/posts/{id}
• GET /api/v1/posts/{id}/comments
• POST /api/v1/posts/{id}/comments
• POST /api/v1/posts/{id}/reactions
• POST /api/v1/posts/{id}/favorites/toggle

认证与治理

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• GET /api/v1/auth/me
• POST /api/v1/reports
• GET /api/v1/admin/moderation
• POST /api/v1/admin/reports/{id}/resolve
• GET /api/v1/appeals
• POST /api/v1/appeals
• GET /api/v1/admin/config-changes

部署说明

仓库根目录提供了可直接使用的容器编排：

• Dockerfile：后端生产镜像
• docker-compose.yml：后端、PostgreSQL 和 Redis 的联动启动

Compose 环境默认使用：

• PostgreSQL 镜像：pgvector/pgvector:pg16
• Redis 镜像：redis:7-alpine

备注

• PostgreSQL 是唯一支持的数据库后端，sqlite 不再支持
• Redis 是必选依赖，不是可选增强项
• 如果你修改了配置结构，记得同步更新 config/runtime_config_sample.json