一个微信朋友圈风格的个人博客系统，支持动态、文章、评论互动、媒体上传、R2 音乐歌单、豆瓣影单、RSS 与后台管理。

推荐使用 Vercel（前后端分离）+ TiDB Cloud / 托管 MySQL + Cloudflare R2 部署，无需维护自己的应用服务器；也保留 VPS + PM2 + Nginx 自托管方案。

本文所有域名、数据库地址、账号和密钥均为占位示例。请使用自己的真实配置，且绝不要提交 .env、数据库密码、R2 Access Key、JWT 密钥或其他 Token 到仓库。

• 朋友圈动态：图文、多图拼图、视频、Live Photo、音乐、链接卡片、豆瓣卡片与地理位置；
• 文章系统：富文本编辑、封面、标签、目录、归档时间线；
• 评论互动：楼层评论、回复折叠、表情、点赞、邮件通知；
• 媒体与音乐：媒体直传 Cloudflare R2，R2 音频歌单、LRC 歌词、浮窗播放器；
• 豆瓣影单：同步电影、图书和音乐收藏，支持筛选与分页；
• 后台管理：动态、文章、评论、媒体、友链、广告、音乐、黑名单、SMTP、高德地图、豆瓣、RSS 与站点设置；
• 体验与 SEO：响应式布局、夜间模式、RSS Feed、SSR 与 OG 标签。

该方案将前端、后端作为两个独立的 Vercel 项目部署：

浏览器
  │
  ▼
Vercel 前端（frontend）
  │  浏览器访问 /api/*；Next.js 在服务端转发请求
  ▼
Vercel 后端（backend）
  ├──► TiDB Cloud / 托管 MySQL（业务数据）
  └──► Cloudflare R2（图片、视频、音频等媒体）

建议准备三个稳定的 Origin：

不要将每次构建产生的 Vercel Preview URL 当作长期配置。Preview URL 可能变化，会导致 CORS、R2 上传和回调配置失效。

• GitHub 或 Gitee 仓库；
• Vercel 账号；
• TiDB Cloud 或其他可公网连接的 MySQL 兼容数据库；
• Cloudflare 账号与 R2 Bucket；
• Node.js 20+ 与 pnpm（用于本地初始化目标数据库）；
• 可选：已托管到 Cloudflare 的域名，用于 R2 媒体自定义域名。

在 TiDB Cloud SQL Editor、云数据库控制台或 MySQL 客户端中创建数据库，例如：

CREATE DATABASE moment_blog
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

记录数据库服务提供的以下信息：

Host
Port
Username
Password
Database name
是否要求 SSL/TLS

TiDB Cloud 等托管服务通常要求 TLS；请以控制台的 Connect 页面为准。常见配置为：

DB_SSL=true

db:init 只初始化一个已经存在的数据库，不会执行 CREATE DATABASE。如果报 Unknown database，请先完成本步骤。

下载源码后，在本地进入后端目录：

cd backend
pnpm install

复制环境变量模板：

# macOS / Linux
cp .env.example .env

# Windows PowerShell
# Copy-Item .env.example .env

编辑 backend/.env，让它指向目标数据库。以下仅为示例：

DB_HOST=<your-database-host>
DB_PORT=<your-database-port>
DB_USER=<your-database-user>
DB_PASSWORD=<your-database-password>
DB_NAME=moment_blog
DB_SSL=true

# 仅在首次尚无管理员时用于创建管理员
ADMIN_EMAIL=admin@example.com
ADMIN_USERNAME=admin
ADMIN_PASSWORD=<choose-a-strong-password>

执行唯一的官方数据库初始化命令：

pnpm db:init

db:init 会：

1. 验证数据库连接；
2. 创建缺失的项目数据表；
3. 补齐当前支持的兼容字段；
4. 创建缺失的站点设置记录；
5. 创建默认音乐歌单；
6. 首次不存在管理员时创建管理员。

该命令可安全重复运行：不会删除业务数据，不会重置已有管理员密码，也不会在已有数据上使用 alter 或 force。

正式部署请在本地、CI 或受信任的维护环境中显式运行 pnpm db:init。应用启动及 Vercel 冷启动默认只连接数据库，不会自动执行 DDL。不要将 DB_SYNC_ON_BOOT=true 作为常规生产部署方案。

Vercel Serverless 的文件系统不持久。生产环境的图片、视频、音频等媒体必须使用 R2 等对象存储保存。

1. 在 Cloudflare Dashboard 中进入 R2 → Create bucket；
2. 创建 Bucket，例如 moment-media；
3. 进入 R2 → Manage R2 API Tokens；
4. 创建具备 Object Read & Write 权限的 API Token；
5. 保存以下信息，稍后只填入后端环境变量：

Cloudflare Account ID
Access Key ID
Secret Access Key
Bucket 名称

在 Bucket 设置中绑定一个稳定的公开自定义域名，例如：

https://media.example.com

该域名必须同时用于：

后端 R2_PUBLIC_URL
前端 NEXT_PUBLIC_MEDIA_ORIGIN

两者必须完全相同，且不要带末尾 /：

正确：https://media.example.com
错误：https://media.example.com/

浏览器上传媒体时，会通过后端签发的预签名 URL 直接 PUT 到 R2。R2 Bucket 需要独立配置 CORS；后端的 CLIENT_URL 或 CORS_ALLOWED_ORIGINS 不能替代它。

在 R2 → Bucket → Settings → CORS Policy 中配置。生产模板如下：

[
  {
    "AllowedOrigins": [
      "https://example.com",
      "https://www.example.com"
    ],
    "AllowedMethods": ["PUT", "GET", "HEAD"],
    "AllowedHeaders": ["Content-Type"],
    "ExposeHeaders": ["ETag", "cf-ray", "x-amz-request-id"],
    "MaxAgeSeconds": 3600
  }
]

本地开发时，可额外加入：

http://localhost:3000

注意：

• AllowedOrigins 应填写浏览器中打开前端页面的完整 Origin；
• 不要将 API 域名或 R2 媒体域名填进去，除非页面确实从该 Origin 提供；
• 如果使用前端 Vercel Production 域名测试，也要把它加入；
• 生产环境不要使用 "AllowedOrigins": ["*"]。

在 Vercel 中导入仓库并创建第一个项目：

项目内已有 backend/vercel.json，它会配置 Serverless Function 重写和豆瓣同步 Cron。Vercel 会自动注入 VERCEL=1，无需手动设置。

在 Settings → Environment Variables 中配置 Production 环境变量。

后端配置示例：

NODE_ENV=production

DB_HOST=<your-database-host>
DB_PORT=<your-database-port>
DB_USER=<your-database-user>
DB_PASSWORD=<your-database-password>
DB_NAME=moment_blog
DB_SSL=true

JWT_SECRET=<a-random-secret-at-least-32-characters>
JWT_EXPIRES_IN=7d

CLIENT_URL=https://example.com
REVALIDATE_SECRET=<another-random-secret>
CRON_SECRET=<another-independent-random-secret>

R2_ACCOUNT_ID=<your-cloudflare-account-id>
R2_ACCESS_KEY_ID=<your-r2-access-key-id>
R2_SECRET_ACCESS_KEY=<your-r2-secret-access-key>
R2_BUCKET=moment-media
R2_PUBLIC_URL=https://media.example.com

JWT_SECRET、REVALIDATE_SECRET 与 CRON_SECRET 应使用彼此不同的随机值。

ADMIN_EMAIL、ADMIN_USERNAME、ADMIN_PASSWORD 只在本地首次运行 db:init 且数据库中尚无管理员时使用。数据库初始化完成后，它们不是 Vercel 后端运行时必填变量。

再次从同一仓库创建第二个 Vercel 项目：

在前端项目的 Settings → Environment Variables 中配置：

示例：

NEXT_PUBLIC_API_URL=/api
BACKEND_URL=https://api.example.com
NEXT_PUBLIC_SITE_URL=https://example.com
NEXT_PUBLIC_MEDIA_ORIGIN=https://media.example.com
REVALIDATE_SECRET=<the-same-value-as-backend>

以下关系必须成立：

frontend.REVALIDATE_SECRET = backend.REVALIDATE_SECRET
frontend.NEXT_PUBLIC_MEDIA_ORIGIN = backend.R2_PUBLIC_URL

不要使用以下变量保存密钥：

NEXT_PUBLIC_REVALIDATE_SECRET
NEXT_PUBLIC_CRON_SECRET

任何 NEXT_PUBLIC_ 前缀变量都会在前端构建时暴露给浏览器。

浏览器请求：

https://example.com/api/posts

Next.js 通过 BACKEND_URL 在服务端转发到：

https://api.example.com/api/posts

因此不要将 NEXT_PUBLIC_API_URL 写成完整后端地址。保持 /api 可减少浏览器跨域 Cookie 问题；域名变化时也不需要重写客户端 API 路径。

建议将稳定 Production 域名绑定到 Vercel：

前端：https://example.com
后端：https://api.example.com
R2：https://media.example.com

绑定完成后，重新检查：

# frontend
BACKEND_URL=https://api.example.com
NEXT_PUBLIC_SITE_URL=https://example.com
NEXT_PUBLIC_MEDIA_ORIGIN=https://media.example.com

# backend
CLIENT_URL=https://example.com
R2_PUBLIC_URL=https://media.example.com

修改环境变量后，请分别对前端和后端项目执行一次 Redeploy。

特别注意：NEXT_PUBLIC_MEDIA_ORIGIN 会在前端构建期用于 Next Image 远程域名白名单。更换 R2 媒体域名后，必须重新构建前端。

如果测试 Vercel Preview 部署：

1. 使用稳定的 Preview 域名，或记录实际 Preview 的完整 Origin；
2. 将该 Origin 加入后端 CORS_ALLOWED_ORIGINS；
3. 同时将其加入 R2 Bucket 的 AllowedOrigins；
4. 不要长期依赖随分支变化的 Preview 地址作为生产配置。

1. 访问后端健康检查：

   https://api.example.com/api/health
   

   预期返回：

   { "status": "ok", "timestamp": "..." }

2. 打开前端站点，确认 Network 面板中请求路径为：

   /api/posts
   /api/settings
   /api/friends
   

3. 使用 db:init 创建的管理员账号登录：

   https://example.com/admin/login
   

4. 上传一张测试图片或音频：确认对象上传到 R2，且可通过 R2_PUBLIC_URL 对应的媒体域名访问；

5. 发布一条测试动态，确认列表刷新和页面重验证正常；

6. 如启用了豆瓣影单，确认后端已配置 CRON_SECRET，并检查当前 Vercel 套餐是否支持 Cron Jobs。若不支持，可使用外部调度器定时调用该接口。

如果希望自行维护服务器、MySQL、Nginx、SSL 与进程守护，可以使用以下方案。新部署优先推荐前面的 Vercel 方案；VPS 模式适合需要固定出口 IP、局域网数据库或完整服务器控制权的场景。

• Debian 12 服务器（root 或 sudo 权限）；
• 一个域名（推荐）；
• 云服务商安全组已放行 80、443 与 22 端口；
• 已准备 Cloudflare R2，作为持久媒体存储。

apt update && apt upgrade -y
apt install -y curl wget git vim build-essential nginx mysql-server

# 安装 Node.js 20 LTS
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs

# 启用 pnpm 并安装 PM2
corepack enable
corepack prepare pnpm@latest --activate
npm install -g pm2

验证：

node -v
pnpm -v
pm2 -v

systemctl enable --now mysql
mysql -u root -p

在 MySQL 中执行：

CREATE DATABASE moment_blog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'kanle'@'localhost' IDENTIFIED BY '<choose-a-strong-password>';
GRANT ALL PRIVILEGES ON moment_blog.* TO 'kanle'@'localhost';
FLUSH PRIVILEGES;
EXIT;

INSTALL_DIR=/opt/kanle

# 国内服务器可使用 Gitee
# git clone https://gitee.com/ziln_cn/kanle.git $INSTALL_DIR

git clone https://github.com/zilinnb/kanle.git $INSTALL_DIR
cd $INSTALL_DIR/backend
pnpm install
cp .env.example .env

编辑 .env。至少设置数据库、JWT、前端 Origin、重验证密钥及完整 R2 配置：

DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=kanle
DB_PASSWORD=<your-database-password>
DB_NAME=moment_blog

JWT_SECRET=<a-random-secret-at-least-32-characters>
CLIENT_URL=https://example.com
REVALIDATE_SECRET=<another-random-secret>

R2_ACCOUNT_ID=<your-cloudflare-account-id>
R2_ACCESS_KEY_ID=<your-r2-access-key-id>
R2_SECRET_ACCESS_KEY=<your-r2-secret-access-key>
R2_BUCKET=moment-media
R2_PUBLIC_URL=https://media.example.com

构建、初始化并启动：

pnpm build
pnpm db:init
pm2 start ecosystem.config.js
pm2 save

检查：

curl http://127.0.0.1:4000/api/health

cd $INSTALL_DIR/frontend
pnpm install
cp .env.example .env.local

配置 frontend/.env.local：

NEXT_PUBLIC_API_URL=/api
BACKEND_URL=http://127.0.0.1:4000
NEXT_PUBLIC_SITE_URL=https://example.com
NEXT_PUBLIC_MEDIA_ORIGIN=https://media.example.com
REVALIDATE_SECRET=<the-same-value-as-backend>

PORT=3000
HOSTNAME=0.0.0.0

构建并启动：

pnpm build
cp -r .next/static .next/standalone/.next/static
pm2 start ecosystem.config.js
pm2 save

检查：

curl http://127.0.0.1:3000

复制并编辑项目提供的配置：

cp $INSTALL_DIR/deploy/nginx.conf /etc/nginx/conf.d/kanle.conf
vim /etc/nginx/conf.d/kanle.conf

将其中的：

server_name yourdomain.com
/opt/kanle

分别替换为实际域名与安装目录。然后验证并重载：

nginx -t
nginx -s reload

安装证书工具并申请 HTTPS 证书：

apt install -y certbot python3-certbot-nginx
certbot --nginx -d example.com
certbot renew --dry-run

设置防火墙与 PM2 开机启动：

ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable

pm2 startup
# 按提示执行输出的命令
pm2 save

这些值由 pnpm db:init 使用。已有管理员后，再修改这些值不会重置已有账号密码。

1. 在部署前备份数据库；

2. 更新仓库代码；

3. 如版本说明提及模型或兼容字段更新，在受信任维护环境中让 .env 指向目标数据库后运行：

   cd backend
   pnpm install
   pnpm db:init

4. 在 Vercel 重新部署前端与后端项目；

5. 检查健康接口、登录和媒体上传。

db:init 不执行历史业务数据迁移、R2 音乐迁移或点赞重置。此类脚本必须按对应版本说明操作，并在执行前备份数据库；不要将它们作为首次安装步骤。

cd $INSTALL_DIR
git pull

cd backend
pnpm install
pnpm build
pnpm db:init
pm2 restart kanle-backend

cd ../frontend
pnpm install
pnpm build
cp -r .next/static .next/standalone/.next/static
pm2 restart kanle-frontend

登录 /admin 后可以配置：

cd backend
node dist/scripts/reset-password.js

pm2 logs kanle-backend
pm2 logs kanle-frontend
pm2 logs

# 后端
cd backend
pnpm install
cp .env.example .env
# 编辑 .env 并指向一个已创建的本地/测试数据库
pnpm db:init
pnpm dev

另开一个终端：

# 前端
cd frontend
pnpm install
cp .env.example .env.local
pnpm dev

首次开发和生产部署都应显式运行 pnpm db:init；应用启动默认不会自动变更数据库表结构。

MIT

Copyright (c) 2026 reii