中文 | English
LinkCloud 是一个基于 Go 语言开发的短链接管理服务，提供短链接的创建、管理、访问统计等完整功能。
- 语言: Go 1.26.1
- Web 框架: Gin
- 数据库: MySQL (GORM)
- 缓存: Redis
- 认证: JWT (golang-jwt)
- 邮件: go-mail
- CI/CD: Gitea Actions
LinkCloud/
├── main.go # 程序入口
├── config/ # 配置加载
│ ├── config.go
│ └── config.yaml
├── controller/ # HTTP 请求处理层
│ ├── auth.go # 认证相关接口
│ ├── link.go # 短链接 CRUD 接口
│ ├── stats.go # 统计数据接口
│ └── user.go # 用户信息接口
├── database/ # 数据库与 Redis 连接管理
│ └── database.go
├── dto/ # 请求/响应数据结构定义
│ ├── auth.go
│ ├── link.go
│ ├── stats.go
│ └── user.go
├── ecode/ # 统一错误码定义
│ └── code.go
├── middleware/ # 中间件
│ ├── auth.go # JWT 认证中间件
│ └── rate_limit.go # 令牌桶限流中间件
├── model/ # 数据库模型
│ ├── short_link.go
│ └── user.go
├── repository/ # 数据访问层
│ ├── captcha.go # 验证码存储
│ ├── security.go # 安全相关 Redis 操作
│ ├── short_link.go # 短链接数据操作
│ ├── stats.go # 统计数据查询
│ └── user.go # 用户数据操作
├── routes/ # 路由定义
│ └── routes.go
├── service/ # 业务逻辑层
│ ├── auth.go # 认证业务逻辑
│ ├── link.go # 短链接业务逻辑
│ ├── stats.go # 统计业务逻辑
│ └── user.go # 用户业务逻辑
├── templates/ # HTML 模板
│ ├── reset_password.html
│ ├── short_link_password.html
│ └── verification_code.html
└── utils/ # 工具函数
├── crypto.go # 密码加密
├── email.go # 邮件发送
├── jwt.go # JWT 生成与解析
├── url.go # URL 校验
└── validation.go # 输入校验
- 邮箱注册: 通过邮箱验证码完成注册，防止恶意注册
- 登录/登出: 基于 JWT 的身份认证，支持 Access Token
- 密码重置: 通过邮箱发送重置链接，链接有效期 1 小时
- 配额管理: 每个用户拥有短链接创建配额（默认 100），防止滥用
- 创建短链接: 将长 URL 转换为 6 位随机短码（大小写字母 + 数字）
- 自定义属性:
- 备注 (Remark)
- 密码保护 - 访问时需输入密码
- 过期时间 - 支持设置链接过期时间，过期后自动失效
- 启用/禁用状态
- CRUD 操作: 支持创建、查询列表（分页 + 排序 + 模糊搜索）、查看详情、更新、删除
- 软删除: 删除操作为软删除，数据可恢复
- 短链接跳转: 访问
/:short_code自动跳转到原始 URL - 密码保护跳转: 需要密码的链接会跳转到密码输入页面
- 访问日志: 记录每次访问的 IP、User-Agent、Referer、设备类型（PC/Mobile/Tablet）、时间等
- 按月分表: 访问日志按月自动分表存储 (
access_logs_YYYYMM) - 点击统计: 支持查询指定天数（最多 90 天）的每日点击量统计
- 日志查询: 支持分页查询访问日志，可按时间范围过滤
- 令牌桶限流: 基于 Redis 的令牌桶算法，对关键接口进行限流保护
- 注册: 10 容量，5/秒填充
- 验证码发送: 5 容量，1/秒填充
- 密码重置: 6 容量，3/秒填充
- 短链接访问: 50 容量，25/秒填充
- 登录保护: 同一 IP + 用户名连续 5 次密码错误，锁定 15 分钟
- 密码保护锁定: 短链接密码连续 5 次错误，锁定 5 分钟
- 验证码冷却: 同一邮箱 60 秒内只能发送一次验证码
- 密码哈希: 使用 bcrypt 进行密码加密存储
- 短链接缓存: 热门短链接数据缓存到 Redis，提升跳转性能
- 异步更新: 创建/更新短链接时异步写入缓存，不阻塞主流程
- 缓存穿透保护: 缓存未命中时回源查询数据库，并异步回填缓存
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/auth/register |
用户注册 |
| POST | /api/v1/auth/login |
用户登录 |
| POST | /api/v1/auth/captcha |
发送邮箱验证码 |
| POST | /api/v1/auth/forgot |
忘记密码（发送重置链接） |
| GET | /api/v1/auth/reset/validate |
验证重置链接有效性 |
| POST | /api/v1/auth/reset |
重置密码 |
| GET | /:short_code |
短链接跳转 |
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/v1/links |
创建短链接 |
| GET | /api/v1/links |
获取短链接列表 |
| GET | /api/v1/links/:short_code |
获取短链接详情 |
| PATCH | /api/v1/links/:short_code |
更新短链接 |
| DELETE | /api/v1/links/:short_code |
删除短链接 |
| GET | /api/v1/stats/:short_code |
获取点击统计数据 |
| GET | /api/v1/stats/:short_code/logs |
获取访问日志 |
| GET | /api/v1/user/info |
获取用户信息 |
| PATCH | /api/v1/user/info |
更新用户信息 |
| POST | /api/v1/auth/logout |
退出登录 |
- Go 1.26.1+
- MySQL 5.7+
- Redis 6.0+
编辑 LinkCloud/config/config.yaml:
MySQL:
host: "127.0.0.1"
port: 3306
user: root
password: "your_password"
schema: linkcloud
Redis:
host: "127.0.0.1"
port: 6379
password: "your_password"
jwt_secret: "your_jwt_secret"cd LinkCloud
go mod download
go run main.go服务默认监听 0.0.0.0:8080。
cd LinkCloud
go build -trimpath -ldflags "-s -w" -o linkcloud .| 范围 | 说明 |
|---|---|
| 0 | 成功 |
| 1000-1099 | 通用错误（参数无效、未登录等） |
| 1100-1199 | 认证/用户相关（验证码、用户名密码错误等） |
| 1200-1299 | 短链接相关（链接不存在、过期、密码错误等） |
| 1300-1399 | 统计/日志相关 |
| 1900-1999 | 系统错误（系统繁忙、请求过多） |
完整的错误码列表见 document/error-codes.md。