Dart Frog Test

一个基于 Dart Frog 构建的 ActivityPub 联邦社交网络后端服务，支持 JWT 认证、多数据库、任务队列等企业级功能。

✨ 功能特性

核心功能

• 🔐 JWT 认证系统 - 完整的用户注册、登录、令牌刷新机制
• 🌐 ActivityPub 支持 - 符合 W3C 规范的联邦协议实现
• 📦 多数据库支持 - SQLite、PostgreSQL、MySQL、MongoDB
• 🔄 任务队列 - 支持异步任务处理和定时任务
• 🚀 缓存系统 - 内存缓存和 Redis 支持

ActivityPub 特性

• 👤 Actor 管理（用户资料、关注者/关注中集合）
• 📝 Note 活动（创建、点赞、分享、评论）
• 📨 Inbox/Outbox 实现
• 🔗 WebFinger 服务发现
• 🔒 HTTP Signatures 签名验证
• 🌍 共享 Inbox 支持联邦推送

安全特性

• 🔑 Argon2/Bcrypt 密码哈希
• 🛡️ 角色权限控制（guest、user、admin、superadmin）
• ⏱️ 登录尝试限制和账户锁定
• 🚦 请求速率限制
• 🎫 长期令牌和密钥令牌支持

运维特性

• 📊 Prometheus 指标导出
• 🔍 分布式追踪支持
• 📝 结构化日志（JSON/文本格式）
• 🏥 健康检查端点
• 📖 OpenAPI/Swagger 文档自动生成

🚀 快速开始

环境要求

• Dart SDK >= 3.0.0

安装依赖

dart pub get

开发模式（零配置）

dart_frog dev

服务将在 http://localhost:8080 启动，无需任何配置即可开始开发！

测试 API

# 健康检查
curl http://localhost:8080/health

# 用户注册
curl -X POST http://localhost:8080/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com","password":"Test123456!"}'

# 用户登录
curl -X POST http://localhost:8080/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"Test123456!"}'

📚 API 文档

认证端点 (/auth)

方法	路径	描述	认证
POST	/auth/register	用户注册	❌
POST	/auth/login	用户登录	❌
POST	/auth/logout	用户登出	✅
POST	/auth/refresh	刷新令牌	❌
POST	/auth/long-lived-token	获取长期令牌	✅
POST	/auth/revoke-long-lived-token	撤销长期令牌	✅
GET	/auth/register/status/{taskId}	查询异步注册状态	❌

用户端点 (/users)

方法	路径	描述	认证
GET	/users/me	获取当前用户信息	✅
GET	/users/{username}	获取用户公开资料	❌
GET	/users/{username}/followers	获取关注者列表	❌
GET	/users/{username}/following	获取关注中列表	❌
GET	/users/{username}/outbox	获取用户活动集合	❌
GET	/users/{username}/inbox	获取用户收件箱	✅
POST	/users/{username}/inbox	接收联邦活动	❌
GET	/users/{username}/liked	获取点赞集合	❌

管理端点 (/admin)

方法	路径	描述	认证
POST	/admin/secret-token	生成密钥令牌	admin
POST	/admin/secret-token/verify	验证密钥令牌	❌
GET	/admin/users	获取用户列表	admin

系统端点

方法	路径	描述	认证
GET	/health	健康检查	❌
GET	/api/docs	OpenAPI JSON 文档	❌
GET	/swagger	Swagger UI	❌
GET	/.well-known/webfinger	WebFinger 服务发现	❌
POST	/inbox	共享 Inbox	❌
POST	/media	媒体文件上传	✅

使用 API 文档

方式一：Swagger UI（本地）

访问 http://localhost:8080/swagger，Swagger UI 会自动加载 OpenAPI 文档。

注意：Swagger UI 从 unpkg.com CDN 加载资源，如果网络受限，请使用方式二。

方式二：在线 Swagger Editor

1. 访问 http://localhost:8080/api/docs 获取 OpenAPI JSON
2. 复制 JSON 内容
3. 打开 https://editor.swagger.io
4. 粘贴 JSON 即可查看完整 API 文档

方式三：命令行

# 获取 OpenAPI 文档
curl http://localhost:8080/api/docs

# 健康检查
curl http://localhost:8080/health

API 响应格式

所有 API 响应遵循统一格式：

{
  "success": true,
  "message": "操作成功",
  "data": { ... },
  "statusCode": 200
}

错误响应：

{
  "success": false,
  "message": "错误描述",
  "errorCode": "INVALID_CREDENTIALS",
  "statusCode": 401
}

⚙️ 配置

环境变量

复制 .env.example 到 .env 并根据需要修改：

cp .env.example .env

主要配置项

变量	描述	默认值
ENVIRONMENT	运行环境	development
BASE_URL	服务基础 URL	http://localhost:8080
JWT_SECRET	JWT 密钥（生产环境必须 32+ 字符）	自动生成
DB_TYPE	数据库类型	sqlite
DB_PATH	SQLite 数据库路径	data/dart_frog_test.db

数据库配置

SQLite（开发环境默认）

DB_TYPE=sqlite
DB_PATH=data/dart_frog_test.db

PostgreSQL

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=dart_frog_test
DB_USERNAME=your_username
DB_PASSWORD=your_password

MySQL

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=dart_frog_test
DB_USERNAME=your_username
DB_PASSWORD=your_password

MongoDB

DB_TYPE=mongodb
DB_HOST=localhost
DB_PORT=27017
DB_NAME=dart_frog_test
DB_USERNAME=your_username
DB_PASSWORD=your_password

开发模式特性

在 development 环境下：

• ✅ 使用 SQLite 数据库
• ✅ 自动生成 JWT 密钥
• ✅ 宽松的密码策略（最少 4 位）
• ✅ Debug 级别日志
• ✅ 禁用 Prometheus 指标
• ✅ 宽松的 HTTP 签名验证

🏗️ 项目结构

dart_frog_test/
├── lib/
│   └── src/
│       ├── activitypub/     # ActivityPub 协议实现
│       │   ├── actor.dart   # Actor 模型
│       │   ├── note.dart    # Note 活动
│       │   ├── collection.dart # 集合类型
│       │   └── http_signature.dart # HTTP 签名
│       ├── cache/           # 缓存系统
│       ├── config/          # 配置管理
│       ├── database/        # 数据库层
│       │   └── adapters/    # 数据库适配器
│       ├── events/          # 事件总线
│       ├── middleware/      # 中间件
│       ├── models/          # 数据模型
│       ├── openapi/         # OpenAPI 文档生成
│       ├── queue/           # 任务队列
│       ├── services/        # 业务服务
│       ├── utils/           # 工具函数
│       ├── versioning/      # API 版本控制
│       └── webfinger/       # WebFinger 服务
├── routes/                  # API 路由
│   ├── admin/              # 管理接口
│   ├── api/                # API 文档
│   ├── auth/               # 认证接口
│   ├── users/              # 用户接口
│   └── .well-known/        # WebFinger
├── test/                    # 测试文件
├── public/                  # 静态文件
└── main.dart               # 应用入口

🧪 测试

运行所有测试

dart test

运行特定测试

dart test test/unit/models/models_test.dart

测试结构

test/
├── test_helpers.dart       # 测试辅助函数和 Mock 类
└── unit/
    ├── models/             # 模型单元测试
    └── utils/              # 工具函数单元测试

🚢 生产部署

构建生产版本

dart_frog build

生产环境配置

ENVIRONMENT=production
BASE_URL=https://your-domain.com
JWT_SECRET=your-super-secret-key-at-least-32-characters-long
DB_TYPE=postgresql
DB_HOST=your-db-host
DB_PORT=5432
DB_NAME=dart_frog_test
DB_USERNAME=your_username
DB_PASSWORD=your_password

运行生产服务器

dart run build/server.dart

Docker 部署

FROM dart:stable

WORKDIR /app
COPY . .

RUN dart pub get
RUN dart_frog build

ENV ENVIRONMENT=production
EXPOSE 8080

CMD ["dart", "run", "build/server.dart"]

🔒 安全最佳实践

1. 生产环境必须设置

   • JWT_SECRET: 至少 32 个字符的强密钥
   • BASE_URL: 你的域名
   • 使用外部数据库而非 SQLite

2. 密码策略

   • 生产环境默认要求 8+ 字符
   • 包含大小写字母、数字、特殊字符

3. HTTPS

   • 生产环境必须使用 HTTPS
   • 建议使用反向代理（Nginx、Caddy）

4. 数据库安全

   • 使用强密码
   • 限制数据库访问 IP
   • 定期备份

📖 ActivityPub 合规性

本项目实现符合 W3C ActivityPub 规范：

• ✅ Actor 端点（用户资料、inbox、outbox）
• ✅ 集合类型（OrderedCollection、Collection）
• ✅ 活动类型（Create、Like、Announce、Follow）
• ✅ WebFinger 服务发现
• ✅ HTTP Signatures 验证
• ✅ bto/bcc 字段投递时移除
• ✅ 共享 Inbox 支持
• ✅ 点赞/分享集合

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

MIT License

---