zhenxijs/ShortLlinkStatisticsAndDistributionPlatform

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

master

fix: 修复路由及数据库会话等多个问题

app
docker
scripts
.env.example
.gitignore
.python-version
CORE.md
README.md
TODO.md
check_db.py
docker-compose.yml
pyproject.toml
test_create_multiplatform.sh
test_multiplatform.json
test_payload.json
test_repo.py
uv.lock

ShortLink Platform

基于 DDD (领域驱动设计) 架构的短链接管理平台，支持自定义卡片、批量创建、来源统计。

📖 DDD 核心概念说明：CORE.md

功能特性

✅ 用户注册/登录 (JWT 认证)
✅ 创建短链接，支持自定义短码
✅ 批量创建短链接
✅ 自定义分享卡片 (微信/钉钉/微博/飞书/QQ 等)
✅ 访问统计 (PV/UV、地域分布、设备类型、来源分析)
✅ 自定义域名
✅ Redis 缓存
✅ Docker 一键部署

技术栈

后端: FastAPI (Python 3.10+)
数据库: PostgreSQL + SQLAlchemy (异步)
缓存: Redis
认证: JWT
包管理: uv
部署: Docker + Docker Compose
架构: DDD (领域驱动设计)

快速开始

使用 Docker Compose

# 1. 克隆项目
cd /workspace/shortlink-platform

# 2. 复制环境变量文件
cp .env.example .env

# 3. 启动所有服务
docker-compose up -d

# 4. 访问应用
# API 文档: http://localhost:8000/api/docs
# 管理后台: http://localhost:8000

本地开发

# 1. 安装依赖 (需要 uv，参考 https://docs.astral.sh/uv/getting-started/installation/)
uv sync

# 2. 配置环境变量
cp .env.example .env

# 3. 启动 PostgreSQL 和 Redis (或使用 Docker)
docker-compose up -d postgres redis

# 4. 初始化数据库
uv run python scripts/init_db.py

# 5. 启动服务
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

项目结构

shortlink-platform/
├── app/
│   ├── domain/                  # 领域层
│   │   ├── shared/             # 共享内核
│   │   ├── user/               # 用户子域
│   │   ├── short_link/         # 短链子域 (核心)
│   │   ├── access_log/         # 访问日志子域
│   │   └── custom_domain/      # 自定义域名子域
│   ├── application/            # 应用层 (CQRS)
│   │   ├── commands/           # 命令
│   │   ├── queries/            # 查询
│   │   ├── handlers/           # 命令/查询处理器
│   │   └── dto/                # 数据传输对象
│   ├── infrastructure/         # 基础设施层
│   │   ├── persistence/        # 数据持久化
│   │   ├── security/           # 安全 (JWT, 密码加密)
│   │   ├── cache/              # 缓存 (Redis)
│   │   └── config/             # 配置
│   ├── interfaces/             # 接口层
│   │   ├── api/                # REST API
│   │   └── web/                # Web 页面
│   └── main.py                 # 应用入口
├── docker/                      # Docker 配置
├── scripts/                     # 脚本
├── tests/                       # 测试
└── docker-compose.yml

API 使用

认证

# 注册
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username": "test", "email": "test@example.com", "password": "123456"}'

# 登录
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username_or_email": "test", "password": "123456"}'

创建短链接

curl -X POST http://localhost:8000/api/v1/links \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "original_url": "https://example.com",
    "title": "Example 网站",
    "description": "这是一个示例网站",
    "platform": "wechat"
  }'

访问短链接

# 直接访问 (重定向)
curl http://localhost:8000/abc123

# 预览 (查看卡片)
curl http://localhost:8000/abc123/preview

DDD 架构说明

领域层 (Domain Layer)

包含业务逻辑和领域模型：

实体 (Entity): User, ShortLink, AccessLog, CustomDomain
值对象 (Value Object): ShortCode, OriginalURL, CardInfo 等
领域事件 (Domain Event): LinkCreatedEvent, LinkClickedEvent 等
领域服务 (Domain Service): ShortCodeGenerator, LinkAnalyticsService
仓储接口 (Repository Interface): 定义数据访问契约

应用层 (Application Layer)

使用 CQRS 模式：

命令 (Command): 创建/更新/删除操作
查询 (Query): 读取操作
处理器 (Handler): 协调领域对象完成任务

基础设施层 (Infrastructure Layer)

提供技术实现：

仓储实现: SQLAlchemy
安全: JWT 认证、密码加密
缓存: Redis
配置: 环境变量管理

接口层 (Interface Layer)

对外暴露接口：

REST API: FastAPI 路由
Web 页面: 管理后台
依赖注入: FastAPI 的 DI 系统

环境变量

参考 .env.example 配置环境变量：

变量	说明	默认值
DATABASE_URL	PostgreSQL 连接字符串	postgresql+asyncpg://postgres:postgres@postgres:5432/shortlink
REDIS_URL	Redis 连接字符串	redis://redis:6379/0
SECRET_KEY	JWT 密钥	your-super-secret-key
ACCESS_TOKEN_EXPIRE_MINUTES	Token 过期时间	1440 (24小时)
BASE_URL	应用基础 URL	http://localhost:8000