LinkShare Blog - 后端 API

基于 NestJS + Bun + PostgreSQL + Redis 的现代化博客后端系统。

---

🚀 快速开始

一键部署（推荐）

# 1. 克隆代码
git clone <your-repo>
cd BingLogyBlog-Backend

# 2. 验证环境
pnpm run verify

# 3. 一键部署
pnpm run deploy

# 4. 验证服务
pnpm run health

# 5. 检查初始化状态（可选）
pnpm run init:status

开发环境快速启动

# 1. 安装依赖
pnpm install

# 2. 启动依赖服务（PostgreSQL + Redis）
docker-compose up -d postgres redis

# 3. 环境验证
cp .env.example .env
# 编辑 .env，至少设置 DATABASE_URL 和 SESSION_COOKIE_SECRET

# 4. 数据库迁移与种子
pnpm run prisma:deploy
pnpm run prisma:seed

# 5. 启动开发服务器
pnpm run start:dev

---

✨ 功能特性

• ✅ 文章管理 - 完整的 CRUD + 分页 + 权限验证 + 查看计数 + 分析追踪
• ✅ 用户系统 - 用户增删改查（仅管理员）+ RBAC 角色权限 + 版主种子用户
• ✅ 评论系统 - 规则审核 + AI 智能审核 + 完整的审计日志
• ✅ 邮件服务 - Nodemailer + HTML 模板 + BullMQ 队列 + 重试机制
• ✅ AI 审核 - OpenRouter 集成 + 自定义提示词 + 容错机制
• ✅ 访客分析 - 事件追踪 + 文章查看统计 + 管理员汇总接口
• ✅ OAuth2 - 完整的 OAuth2 授权服务器实现
• ✅ 管理后台 - 评论管理 + 文章管理 + 用户管理
• ✅ Swagger 文档 - 自动生成 API 文档（开发环境）
• ✅ Docker 部署 - 生产就绪的容器化部署方案

---

🏗️ 技术架构

┌─────────────────┐    ┌──────────────┐    ┌─────────────┐
│   Client App    │────│   API (Nest) │────│  PostgreSQL │
│   (Web/Mobile)  │    │   :3001      │    │   :5432     │
└─────────────────┘    └──────────────┘    └─────────────┘
                              │
                              ├─────────► Redis :6379 (Cache + Queue)
                              │
                              ▼
                       ┌──────────────┐
                       │   BullMQ     │
                       │   Workers    │
                       └──────────────┘

核心技术栈:

• 框架: NestJS 11.x + TypeScript 5.x
• 运行时: Bun 1.1+ (生产优化) / Node.js 20+
• 数据库: PostgreSQL 16+ + Prisma ORM 6.x
• 缓存/队列: Redis 7+ + BullMQ 11.x
• 文档: Swagger/OpenAPI 3.0
• 安全: Helmet, CORS, Rate Limiting, Session + OAuth2
• 邮件: Nodemailer + HTML 模板
• AI: OpenRouter 集成 (BYOK)

---

📦 项目结构

.
├── src/                    # 源代码
│   ├── app.module.ts      # 根模块
│   ├── main.ts            # 入口文件
│   ├── config/            # 配置模块
│   │   ├── config.module.ts
│   │   └── env.ts
│   ├── modules/           # 功能模块
│   │   ├── init/         # 系统初始化
│   │   ├── admin/        # 管理后台
│   │   │   ├── admin-articles/
│   │   │   └── admin-comments/
│   │   ├── articles/     # 文章模块
│   │   ├── users/        # 用户模块
│   │   ├── comments/     # 评论模块
│   │   ├── session/      # 会话管理
│   │   ├── oauth2/       # OAuth2 授权
│   │   ├── email/        # 邮件服务
│   │   ├── moderation/   # 内容审核
│   │   ├── analytics/    # 数据分析
│   │   ├── jobs/         # 任务队列
│   │   ├── prisma/       # 数据库服务
│   │   └── health/       # 健康检查
│   └── types/            # 类型声明
├── scripts/              # 部署脚本
│   ├── verify-env.sh     # 环境验证
│   ├── deploy.sh         # 一键部署
│   ├── backup.sh         # 数据库备份
│   ├── restore.sh        # 数据库恢复
│   ├── healthcheck.sh    # 健康检查
│   └── init-db.sql       # 数据库初始化
├── docker-compose.yml    # Docker Compose 配置
├── Dockerfile.api        # API 镜像构建
├── prisma/              # Prisma Schema
│   ├── schema.prisma
│   ├── seed.ts
│   └── migrations/
├── AGENTS.md            # 开发规范
└── .env.example        # 环境变量模板

---

🔧 快速命令

使用 Package.json Scripts (推荐)

# 查看所有可用命令
pnpm run --help

# 部署相关
pnpm run verify              # 验证环境配置
pnpm run deploy              # 完整生产部署
pnpm run deploy:dev          # 开发环境部署
pnpm run deploy:quick        # 快速部署（跳过构建）
pnpm run deploy:check        # 部署并检查初始化状态
pnpm run migrate             # 仅运行数据库迁移
pnpm run seed                # 仅运行数据库种子

# 服务管理
pnpm run start:all           # 启动所有服务
pnpm run stop                # 停止所有服务
pnpm run restart             # 重启所有服务
pnpm run recreate            # 重新创建服务（会丢失数据！）
pnpm run status              # 查看服务状态
pnpm run stats               # 查看资源使用情况

# 日志查看
pnpm run logs                # 查看所有服务日志
pnpm run logs:api            # 查看 API 日志
pnpm run logs:db             # 查看数据库日志
pnpm run logs:redis          # 查看 Redis 日志

# 健康与初始化
pnpm run health              # 运行健康检查
pnpm run health:init         # 完整健康检查（含初始化）
pnpm run init:status         # 检查初始化状态（需要管理员 Token）
pnpm run init:run            # 手动触发初始化检查
pnpm run init:generate-keys  # 生成 OAuth2 RSA 密钥对

# 数据库管理
pnpm run prisma:generate     # 生成 Prisma Client
pnpm run prisma:deploy       # 部署迁移到数据库
pnpm run prisma:seed         # 运行数据库种子
pnpm run prisma:studio       # 打开 Prisma Studio
pnpm run backup              # 备份数据库
pnpm run restore             # 恢复数据库（需要 BACKUP_FILE 参数）

# 开发相关
pnpm run start:dev           # 开发模式（热重载）
pnpm run start:debug         # 调试模式
pnpm run dev                 # 同 start:dev
pnpm run debug               # 同 start:debug

# 代码质量
pnpm run build               # 构建应用
pnpm run lint                # 代码检查
pnpm run format              # 代码格式化
pnpm run test                # 运行测试
pnpm run test:watch          # 测试（watch 模式）
pnpm run test:cov            # 测试（覆盖率）

# 安全与配置
pnpm run secrets             # 生成随机密钥
pnpm run cert                # 生成自签名证书（仅开发）

# 容器访问
pnpm run shell               # 进入 API 容器
pnpm run shell:db            # 进入数据库容器
pnpm run shell:redis         # 进入 Redis 容器

# 清理
pnpm run clean               # 清理（停止服务并删除未使用的资源）
pnpm run clean:all           # 彻底清理（包括镜像）

# 文档
pnpm run docs                # 显示文档链接

使用脚本（底层）

# 环境验证
./scripts/verify-env.sh

# 一键部署（内部调用 deploy.sh）
./scripts/deploy.sh --production
./scripts/deploy.sh --development

# 健康检查（包含初始化检查）
./scripts/healthcheck.sh
./scripts/healthcheck.sh --admin-token <your-token>

# 数据库操作
./scripts/backup.sh [name]
./scripts/restore.sh <backup_file>

Docker Compose（直接操作）

# 构建镜像
docker-compose build

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

# 查看日志
docker-compose logs -f api

# 重启服务
docker-compose restart

# 停止服务
docker-compose down

# 查看状态
docker-compose ps

# 进入容器
docker-compose exec api sh

---

📊 默认账户

首次部署后，种子脚本自动创建:

角色	邮箱	密码	权限
管理员	admin@example.com	password123	完全权限
版主	moderator@example.com	moderator123	评论审核

⚠️ 重要: 首次登录后请立即修改密码！

---

🔐 安全配置

1. 生成随机密钥

pnpm run secrets
# 或手动
openssl rand -base64 32  # SESSION_COOKIE_SECRET
openssl rand -hex 32    # OAUTH2_CLIENT_SECRET

2. 生成 OAuth2 RSA 密钥对

pnpm run init:generate-keys
# 或手动
openssl genrsa -out oauth2-private.pem 2048
openssl rsa -pubout -in oauth2-private.pem -out oauth2-public.pem

将 PEM 内容复制到 .env 文件。

3. 生产环境必需配置

NODE_ENV=production
SESSION_COOKIE_SECURE=true
APP_BASE_URL=https://api.yourdomain.com
OAUTH2_TOKEN_SIGNING_PRIVATE_KEY=<your-private-key>
OAUTH2_TOKEN_SIGNING_PUBLIC_KEY=<your-public-key>

---

🌐 API 端点概览

认证

• POST /login - JSON 登录
• POST /logout - 登出
• GET /oauth2/authorize - OAuth2 授权
• POST /oauth2/token - 获取 Token
• GET /me - 当前用户信息

文章

• GET /articles - 列表（支持分页、筛选）
• POST /articles - 创建（需登录）
• GET /articles/:id - 详情
• GET /articles/slug/:slug - 根据 slug 获取
• PUT /articles/:id - 更新（作者/管理员）
• DELETE /articles/:id - 删除（作者/管理员）

评论

• POST /articles/:id/comments - 提交评论
• GET /articles/:id/comments - 获取评论

管理后台 (需管理员)

• GET /admin/articles - 文章管理（强制操作）
• GET /admin/comments - 评论管理
• PUT /admin/comments/:id/status - 更新评论状态
• DELETE /admin/comments/:id - 删除评论
• GET /admin/comments/:id/audits - 查看审核日志

系统

• GET /health - 健康检查
• GET /init/status - 初始化状态（管理员）
• POST /init/run - 运行初始化检查（管理员）

完整 API 文档访问 /api-docs (开发环境)。

---

🧪 测试

# 所有测试
pnpm test

# 覆盖率
pnpm run test:cov

# Watch 模式
pnpm run test:watch

# E2E 测试
pnpm run test:e2e

---

📝 开发指南

环境要求

• Node.js 20+ 或 Bun 1.1+
• PostgreSQL 16+
• Redis 7+
• pnpm 8+

开发流程

# 1. 安装依赖
pnpm install

# 2. 复制环境配置
cp .env.example .env
# 编辑 .env 文件

# 3. 启动依赖服务
pnpm run start:all

# 4. 运行迁移
pnpm run prisma:deploy

# 5. 启动开发服务器
pnpm run start:dev

常用命令速查

pnpm run build            # 构建
pnpm run lint             # 代码检查
pnpm run format           # 格式化
pnpm run test             # 测试
pnpm run verify           # 环境验证
pnpm run health           # 健康检查
pnpm run logs:api         # 查看 API 日志
pnpm run shell            # 进入容器

---

🐳 Docker 部署

构建和启动

# 构建镜像
docker-compose build

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

# 查看日志
docker-compose logs -f api

# 停止服务
docker-compose down

资源限制

Docker Compose 已配置:

• CPU: 限制 2 核心，预留 0.5 核心
• 内存: 限制 2GB，预留 512MB
• 日志: 最大 10MB × 3 文件，自动压缩

---

📈 监控和维护

健康检查

# API 健康检查
curl http://localhost:3001/health

# 综合健康检查脚本
./scripts/healthcheck.sh

日志管理

# 实时日志
pnpm run logs:api

# 导出日志 (自动归档)
docker-compose logs api > logs/$(date +%Y%m%d_%H%M%S).log

# 清理旧日志
find logs/ -name "*.log" -mtime +30 -delete

备份数据库

# 手动备份
pnpm run backup

# 自动备份 (添加到 crontab)
0 2 * * * cd /path/to/project && pnpm run backup

恢复数据库

# 查看备份列表
ls -lh backups/

# 恢复指定备份
BACKUP_FILE=backups/daily_20260328.sql.gz pnpm run restore
# 或
./scripts/restore.sh backups/daily_20260328.sql.gz

---

🚨 故障排查

常见问题

1. 容器无法启动

   docker-compose logs api  # 查看错误日志
   docker-compose down && docker-compose up -d  # 重启
   

2. 数据库连接失败

   docker-compose ps postgres  # 检查数据库状态
   docker-compose logs postgres  # 查看数据库日志
   

3. Redis 连接超时

   docker-compose restart redis
   docker-compose logs redis
   

4. 邮件发送失败

   # 检查 SMTP 配置
   docker-compose exec api env | grep SMTP
   # 查看邮件队列
   docker-compose exec api pnpm prisma emailMessage.findMany()
   

5. AI 审核不工作

   # 检查 API Key
   docker-compose exec api env | grep AI_API_KEY
   # 测试 OpenRouter
   curl -H "Authorization: Bearer $AI_API_KEY" https://openrouter.ai/api/v1/models
   

详细故障排查见 README 的"监控和维护"部分。

---

🔒 安全建议

1. ✅ 修改所有默认密码 (admin/moderator)
2. ✅ 使用强随机密钥 (至少 32 位): pnpm run secrets
3. ✅ 启用 HTTPS (Nginx/Traefik + SSL)
4. ✅ 配置防火墙 (仅开放 80, 443, 3001)
5. ✅ 定期更新依赖 (pnpm update)
6. ✅ 设置自动备份 (每日备份 + 异地存储)
7. ✅ 启用审计日志 (监控 CommentAudit 表)
8. ✅ 限制数据库访问 (仅允许 API 容器访问)

---

📚 相关文档

• 部署指南: 见本文档的"快速开始"和"快速命令"部分
• AGENTS.md - 开发规范
• prisma/schema.prisma - 数据库 Schema
• .env.example - 环境变量说明
• scripts/ - 部署脚本集

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

请确保:

• 代码通过 pnpm run lint
• 添加了适当的测试
• 更新了相关文档

---

📄 License

MIT

---

最后更新: 2026-03-28
版本: 1.0.0
维护者: [Your Team]

---

🚀 完整部署指南

本文档的"快速开始"部分提供了基本的部署流程。如需详细的环境配置说明、故障排查、性能优化建议等，请参考以下扩展内容。

环境要求

组件	版本要求	说明
Node.js	≥ 20.0.0	建议使用 Bun 1.0+ 作为替代（更快）
pnpm	≥ 8.0.0	包管理
PostgreSQL	≥ 15.0	数据库
Redis	≥ 7.0	队列与缓存
Docker & Docker Compose	最新稳定版	可选，用于容器化部署
OpenSSL	任意	生成 RSA 密钥对（OAuth2）

环境变量配置详解

核心变量（.env 文件）：

变量名	必填	默认值	说明
NODE_ENV	否	production	运行环境
PORT	否	3001	API 监听端口
DATABASE_URL	是	-	PostgreSQL 连接字符串
REDIS_HOST	否	redis	Redis 主机名
REDIS_PORT	否	6379	Redis 端口
SESSION_COOKIE_SECRET	是	change_me	Session cookie 签名密钥，生产环境必须改为随机长字符串
SESSION_COOKIE_NAME	否	linkshare_session	Cookie 名称
SESSION_COOKIE_SECURE	否	false	HTTPS 时设为 true
SESSION_COOKIE_HTTPONLY	否	true	HttpOnly 防止 XSS
OAUTH2_ISSUER	否	http://localhost:3001	OAuth2 签发者
OAUTH2_ACCESS_TOKEN_TTL_SECONDS	否	3600	Access token 有效期（秒）
OAUTH2_REFRESH_TOKEN_TTL_SECONDS	否	2592000	Refresh token 有效期（秒）
OAUTH2_TOKEN_SIGNING_PRIVATE_KEY	生产必填	-	RSA 私钥（PEM 格式）
OAUTH2_TOKEN_SIGNING_PUBLIC_KEY	生产必填	-	RSA 公钥（PEM 格式）
AI_PROVIDER	否	openrouter	AI 提供商
AI_API_KEY	否	-	AI API 密钥（BYOK）
SMTP_HOST	否	-	SMTP 服务器
SMTP_PORT	否	587	SMTP 端口
SMTP_USER	否	-	SMTP 用户名
SMTP_PASS	否	-	SMTP 密码

完整列表见 .env.example。

生产环境注意事项

1. 修改所有默认密码 (admin/moderator)
2. 使用强随机密钥 (至少 32 位): pnpm run secrets
3. 启用 HTTPS (Nginx/Traefik + SSL)
4. 配置防火墙 (仅开放 80, 443, 3001)
5. 定期更新依赖 (pnpm update)
6. 设置自动备份 (每日备份 + 异地存储)
7. 启用审计日志 (监控 CommentAudit 表)
8. 限制数据库访问 (仅允许 API 容器访问)

故障排查

API 无法启动

docker-compose logs api      # 查看错误日志
docker-compose down && docker-compose up -d  # 重启

数据库连接失败

docker-compose ps postgres   # 检查数据库状态
docker-compose logs postgres # 查看数据库日志

初始化检查失败

# 获取管理员 token 后运行
pnpm run init:status
# 或
./scripts/healthcheck.sh --admin-token <token>