JLONG 博客系统 - 完整部署教程

<div align="center">

🚀 零基础到上线：10分钟完成博客系统部署

本教程将手把手教你将 JLONG 博客系统部署到生产环境

在线演示 | 项目仓库 | 常见问题

</div>

---

📋 目录

• 部署前准备
• 方案一：Vercel + Neon（推荐）
• 方案二：其他平台部署
• 数据库初始化
• 功能配置
• 域名绑定
• 安全加固
• 常见问题
• 维护与更新

---

✅ 部署前准备

1. 所需账号

服务	用途	费用	注册地址
GitHub	代码托管	免费	https://github.com
Vercel	前端部署	免费	https://vercel.com
Neon	PostgreSQL 数据库	免费	https://console.neon.tech
和风天气（可选）	天气 API	免费额度	https://dev.qweather.com

2. 本地环境（可选）

如果需要本地开发：

• Node.js >= 18.0
• Git
• 代码编辑器（VS Code 推荐）

3. 准备工作清单

• 注册 GitHub 账号
• 注册 Vercel 账号（可用 GitHub 登录）
• 注册 Neon 账号（可用 GitHub 登录）
• （可选）注册和风天气账号获取 API Key

---

🚀 方案一：Vercel + Neon（推荐）

⭐ 最佳实践：全球 CDN 加速 + Serverless 数据库，完全免费且性能卓越

步骤 1：Fork 项目到你的 GitHub

1. 访问项目仓库：https://github.com/jinlong5201314/my_blog_mysql
2. 点击右上角 Fork 按钮
3. 等待 Fork 完成（约 10 秒）

步骤 2：创建 Neon PostgreSQL 数据库

2.1 创建数据库

1. 访问 https://console.neon.tech
2. 使用 GitHub 账号登录
3. 点击 Create a project
4. 填写项目信息：
   • Project name: jlong-blog （或任意名称）
   • Region: 选择 AWS / Singapore (ap-southeast-1)
   • PostgreSQL version: 默认最新版本
5. 点击 Create project

2.2 获取数据库连接字符串

1. 在项目页面，找到 Connection string 部分
2. 选择 Pooled connection （连接池模式，性能更好）
3. 复制完整的连接字符串，格式如下：

postgresql://username:password@ep-xxx.ap-southeast-1.aws.neon.tech/dbname?sslmode=require

4. ⚠️ 重要：保存好这个连接字符串，后面会用到！

2.3 初始化数据库表结构

1. 在 Neon 控制台，点击左侧 SQL Editor
2. 复制项目中 sql/init-postgres.sql 文件的全部内容
3. 粘贴到 SQL Editor
4. 点击 Run 执行
5. 看到成功提示：JLONG 博客系统 PostgreSQL 数据库初始化完成！

✅ 数据库创建完成！将会包含以下表：

• admins - 管理员账号
• posts - 文章数据
• settings - 系统设置
• visitor_stats - 访问统计
• visitor_logs - 访问日志

步骤 3：部署到 Vercel

3.1 导入项目

1. 访问 https://vercel.com
2. 使用 GitHub 账号登录
3. 点击 Add New... → Project
4. 在列表中找到你 Fork 的 my_blog_mysql 仓库
5. 点击 Import

3.2 配置环境变量

在 Environment Variables 部分，添加以下变量：

Name	Value	说明
DATABASE_URL	postgresql://...	从 Neon 复制的连接字符串
JWT_SECRET	your-secret-key-here	随机生成的密钥（见下方）
QWEATHER_API_KEY	4ffd366f1b124c92bdb3a7c3c8a3af62	和风天气 Key（可选）

如何生成 JWT_SECRET：

# 方法1：在线生成
访问 https://generate-secret.vercel.app/32

# 方法2：本地生成（需要 Node.js）
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

生成示例：a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

3.3 开始部署

1. 确认所有环境变量已添加
2. 点击 Deploy 按钮
3. 等待部署完成（约 2-3 分钟）
4. 看到 🎉 Congratulations! 表示部署成功

3.4 访问你的博客

部署成功后，Vercel 会提供一个访问地址：

https://my-blog-mysql-xxx.vercel.app

点击 Visit 访问你的博客！

步骤 4：登录管理后台

1. 访问 https://你的域名/admin/login
2. 使用默认管理员账号登录：
   • 用户名：admin
   • 密码：admin123
3. ⚠️ 重要：登录后立即修改密码！
   • 进入「网站设置」→「安全设置」
   • 修改管理员密码

步骤 5：配置天气功能（可选）

5.1 获取和风天气 API Key（如果需要自己的 Key）

1. 访问 https://dev.qweather.com
2. 注册并登录
3. 创建应用获取 API Key
4. 在 Vercel 环境变量中更新 QWEATHER_API_KEY

5.2 设置城市

1. 登录管理后台
2. 进入「网站设置」
3. 找到「天气城市代码」输入框
4. 输入你所在城市的代码（见下方城市代码表）
5. 点击「保存所有设置」

常用城市代码：

城市	Location ID
北京	101010100
上海	101020100
广州	101280101
深圳	101280601
杭州	101210101
成都	101270101
惠州	101280303

完整城市列表：China-City-List

---

🌐 方案二：其他平台部署

Railway 部署

1. 访问 https://railway.app
2. 使用 GitHub 登录
3. New Project → Deploy from GitHub repo
4. 选择你的仓库
5. 添加 PostgreSQL 服务
6. 配置环境变量（同 Vercel）
7. 部署完成

自建服务器部署

适合有服务器的用户：

# 1. 克隆代码
git clone https://github.com/your-username/my_blog_mysql.git
cd my_blog_mysql

# 2. 安装依赖
npm install

# 3. 配置环境变量
cp .env.example .env.local
# 编辑 .env.local 填入数据库连接等信息

# 4. 构建项目
npm run build

# 5. 启动服务
npm start

# 使用 PM2 保持运行
npm install -g pm2
pm2 start npm --name "jlong-blog" -- start
pm2 save

---

💾 数据库初始化

方式一：Neon SQL Editor（推荐）

1. 登录 Neon 控制台
2. 选择你的项目
3. 点击 SQL Editor
4. 复制 sql/init-postgres.sql 内容
5. 粘贴并执行

方式二：本地脚本

如果你 Fork 了代码到本地：

# 1. 设置环境变量
export DATABASE_URL="postgresql://..."

# 2. 运行初始化脚本
node scripts/init-database.js

# 3. 验证数据库
node scripts/verify-database.js

初始化包含内容

• ✅ 创建 5 个数据表
• ✅ 创建 18 个索引
• ✅ 添加默认管理员账号（admin/admin123）
• ✅ 插入 18 个系统配置项
• ✅ 创建数据库触发器

---

⚙️ 功能配置

1. 基本信息设置

登录管理后台 → 网站设置：

• 网站名称: 你的博客名称
• 网站描述: SEO 描述
• 网站关键词: SEO 关键词
• 品牌名称: 显示在导航栏
• 品牌标语: 首页大标题下方文字

2. 外观定制

• 首页背景图: 支持图片 URL 或 API
  • 推荐：https://source.unsplash.com/random/1920x1080
• Logo: 网站 Logo 图片 URL
• 头像: 侧边栏个人头像
• 主题色: 主题色彩（十六进制色码）

3. 天气功能

• 天气城市代码: 和风天气 Location ID
• 天气 API Key: 和风天气 API Key（可选，系统内置测试 Key）

4. 社交链接

• GitHub 主页
• Twitter 账号
• Email 地址

5. 安全设置

• 修改密码: 定期更换管理员密码
• JWT 密钥: 在 Vercel 环境变量中配置

---

🌍 域名绑定

在 Vercel 绑定自定义域名

1. 添加域名

1. 进入 Vercel 项目设置
2. 点击 Domains
3. 输入你的域名（如 myblog.example.com）
4. 点击 Add

2. 配置 DNS

Vercel 会提供 DNS 配置信息，通常有两种方式：

方式一：CNAME 记录（推荐）

在你的域名服务商处添加 DNS 记录：

类型	名称	值
CNAME	myblog（或 @）	cname.vercel-dns.com

方式二：A 记录

类型	名称	值
A	@	76.76.21.21

3. 等待生效

• DNS 生效时间：5 分钟 - 24 小时
• Vercel 自动配置 SSL 证书（Let's Encrypt）
• 支持 HTTPS 自动跳转

示例配置

项目演示站的配置：

• 域名：myblog.1752667613.xyz
• DNS 解析：CNAME → cname.vercel-dns.com
• SSL：自动配置
• HTTP → HTTPS：自动跳转

---

🔒 安全加固

1. 修改默认密码

⚠️ 极其重要！部署后必须立即修改：

1. 登录管理后台
2. 网站设置 → 安全设置
3. 输入当前密码：admin123
4. 输入新密码（建议 16 位以上，包含大小写、数字、符号）
5. 保存

2. JWT 密钥管理

生成强密钥：

# 生成 32 字节随机密钥
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

在 Vercel 环境变量中更新：

1. 项目设置 → Environment Variables
2. 编辑 JWT_SECRET
3. 输入新密钥
4. 重新部署项目

3. 数据库安全

• ✅ Neon 自动启用 SSL
• ✅ 连接字符串使用 ?sslmode=require
• ✅ 不要在代码中硬编码连接字符串
• ✅ 定期备份数据库（Neon 自动每日备份）

4. API 安全

• ✅ 所有管理接口使用 JWT 认证
• ✅ SQL 使用参数化查询，防止注入
• ✅ bcrypt 密码加密（10 轮）
• ✅ 敏感操作记录日志

---

❓ 常见问题

部署相关

Q: Vercel 部署失败怎么办？

A: 检查以下几点：

1. 环境变量是否正确配置
2. 数据库连接字符串是否有效
3. 查看 Vercel 部署日志获取错误信息
4. 确认 Node.js 版本 >= 18

Q: 数据库连接超时？

A:

1. 检查 Neon 数据库是否处于活跃状态
2. 确认连接字符串包含 ?sslmode=require
3. 使用 Pooled connection 而不是 Direct connection
4. 检查 Neon 免费额度是否用完

Q: 网站访问很慢？

A:

1. Vercel 免费版在某些地区可能较慢
2. 考虑绑定自定义域名（国内访问更快）
3. 检查图片大小，使用 CDN 加速
4. Neon 数据库选择离你最近的区域

功能相关

Q: 天气不显示？

A:

1. 检查 QWEATHER_API_KEY 环境变量
2. 确认数据库中 weatherLocationId 设置存在
3. 打开浏览器控制台查看错误信息
4. 验证城市代码是否正确

Q: 上传图片失败？

A:

1. 检查文件大小（< 5MB）
2. 确认文件格式（jpg, png, gif, webp）
3. 查看浏览器控制台网络请求
4. 考虑使用图床服务

Q: 访问统计不工作？

A:

1. 确认数据库表已创建（visitor_stats, visitor_logs）
2. 检查浏览器控制台是否有 API 错误
3. 管理后台页面不会被记录
4. 同一会话访问同一页面只记录一次

管理相关

Q: 忘记管理员密码怎么办？

A:

1. 使用 Neon SQL Editor 连接数据库
2. 执行以下 SQL 重置密码为 admin123：

UPDATE admins
SET password = '$2b$10$ORqCfftzVB/GADRV9YNaTedweX438fv0qae6L7UJwyjFqs/02Ke7i'
WHERE username = 'admin';

3. 登录后立即修改为新密码

Q: 如何备份数据？

A:

1. Neon 自动每日备份
2. 手动导出：Neon SQL Editor → Export
3. 使用 pg_dump 工具：

pg_dump $DATABASE_URL > backup.sql

Q: 如何导入旧文章？

A:

1. 准备 SQL 格式的文章数据
2. 使用 Neon SQL Editor 导入
3. 或使用 API 批量发布（参考 scripts/publish-articles.js）

---

🔄 维护与更新

同步上游更新

当项目有新版本时：

# 1. 添加上游仓库
git remote add upstream https://github.com/jinlong5201314/my_blog_mysql.git

# 2. 获取更新
git fetch upstream

# 3. 合并更新
git merge upstream/main

# 4. 推送到你的仓库
git push origin main

Vercel 会自动部署更新。

监控与日志

Vercel 日志

1. 进入 Vercel 项目
2. 点击 Logs 查看运行日志
3. 可以按时间筛选和搜索

数据库监控

1. Neon 控制台 → Monitoring
2. 查看：
   • 连接数
   • 查询性能
   • 存储使用量
   • 数据传输量

定期维护

建议每月进行：

• 检查并更新依赖包
• 审查访问日志
• 清理旧的访问记录
• 备份重要数据
• 检查安全更新

---

📚 相关文档

• 项目 README
• 天气功能配置指南
• API 上传指南
• 文件管理指南

---

💬 获取帮助

遇到问题？

1. 📖 查看 常见问题
2. 🔍 搜索 GitHub Issues
3. 💬 提交新 Issue
4. 📧 发送邮件：1752667613@qq.com

---

🎉 部署成功检查清单

完成部署后，请确认：

• 网站可以正常访问
• 首页显示正常
• 天气功能正常显示
• 可以登录管理后台
• 已修改默认管理员密码
• 可以创建和发布文章
• 访问统计功能正常
• 自定义域名已绑定（如果有）
• SSL 证书已配置
• 网站设置已自定义

---

<div align="center">

🎊 恭喜！你的博客系统已成功部署！🎊

开始你的写作之旅吧！

返回顶部

</div>