# LinkShare Blog - 后端 API

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

[![NestJS](https://img.shields.io/badge/NestJS-11.x-red)](https://nestjs.com)
[![Bun](https://img.shields.io/badge/Bun-1.1+-blue)](https://bun.sh)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-16+-blue)](https://www.postgresql.org)
[![Redis](https://img.shields.io/badge/Redis-7+-red)](https://redis.io)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

---

## 🚀 快速开始

### 一键部署（推荐）

```bash
# 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
```

### 开发环境快速启动

```bash
# 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 (推荐)

```bash
# 查看所有可用命令
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                # 显示文档链接
```

### 使用脚本（底层）

```bash
# 环境验证
./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（直接操作）

```bash
# 构建镜像
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. 生成随机密钥

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

### 2. 生成 OAuth2 RSA 密钥对

```bash
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. 生产环境必需配置

```env
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` (开发环境)。

---

## 🧪 测试

```bash
# 所有测试
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+

### 开发流程

```bash
# 1. 安装依赖
pnpm install

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

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

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

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

### 常用命令速查

```bash
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 部署

### 构建和启动

```bash
# 构建镜像
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 文件，自动压缩

---

## 📈 监控和维护

### 健康检查

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

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

### 日志管理

```bash
# 实时日志
pnpm run logs:api

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

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

### 备份数据库

```bash
# 手动备份
pnpm run backup

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

### 恢复数据库

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

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

---

## 🚨 故障排查

### 常见问题

1. **容器无法启动**

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

2. **数据库连接失败**

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

3. **Redis 连接超时**

   ```bash
   docker-compose restart redis
   docker-compose logs redis
   ```

4. **邮件发送失败**

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

5. **AI 审核不工作**
   ```bash
   # 检查 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](./AGENTS.md) - 开发规范
- [prisma/schema.prisma](./prisma/schema.prisma) - 数据库 Schema
- [.env.example](./.env.example) - 环境变量说明
- [scripts/](./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](./.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 无法启动**

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

**数据库连接失败**

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

**初始化检查失败**

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