# Kirameku 全栈博客系统宝塔面板搭建教程
## 项目简介
Kirameku 是一个现代化的全栈博客系统，包含以下组件：
– **前端**: Next.js 16 + React 19 + TypeScript
– **后端**: FastAPI + SQLModel + PostgreSQL
– **管理面板**: Vue 3 + Element Plus
– **阅读服务**: reader-master (Java/Kotlin)
本教程介绍如何使用宝塔面板在单台服务器上完整部署所有组件。
—
## 服务器要求
– **CPU**: 2核及以上（编译Next.js需要）
– **内存**: 4GB及以上
– **硬盘**: 20GB及以上
– **系统**: CentOS 8+/Ubuntu 20.04+/Debian 11+
– **域名**: 已解析到服务器IP
—
## 第一步：安装宝塔面板
### 1. 安装宝塔
**CentOS:**
“`bash
yum install -y wget && wget -O install.sh https://download.bt.cn/install/install_6.0.sh && sh install.sh ed8484bec
“`
**Ubuntu/Debian:**
“`bash
wget -O install.sh https://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh ed8484bec
“`
### 2. 登录宝塔面板
安装完成后，会显示面板地址、用户名和密码：
“`
外网面板地址: http://服务器IP:8888/随机字符
内网面板地址: http://内网IP:8888/随机字符
username: xxxxxx
password: xxxxxx
“`
在浏览器中打开外网面板地址，使用提供的账号密码登录。
### 3. 安装基础环境
登录宝塔后，会弹出”推荐安装套件”窗口，选择以下环境：
– **Nginx** – 最新稳定版
– **MySQL** – 可以不装（我们用PostgreSQL）
– **PHP** – 可以不装
– **phpMyAdmin** – 可以不装
– **Pure-Ftpd** – 可选
点击”一键安装”，等待安装完成。
—
## 第二步：安装必要软件
### 1. 安装PostgreSQL
在宝塔面板左侧菜单点击”软件商店”，搜索并安装：
– **PostgreSQL** – 安装最新版本（15或16）
### 2. 安装PM2管理器
在软件商店搜索并安装：
– **PM2管理器** – 用于管理Node.js进程
### 3. 安装Java
在终端中执行：
“`bash
# 安装OpenJDK 17
yum install -y java-17-openjdk-devel # CentOS
apt install -y openjdk-17-jdk # Ubuntu/Debian
# 验证安装
java -version
“`
### 4. 安装Python 3.11
“`bash
# CentOS 8+
dnf install -y python3.11 python3.11-pip
# Ubuntu 22.04+
apt install -y python3.11 python3.11-venv python3.11-pip
# 验证
python3.11 –version
“`
—
## 第三步：配置数据库
### 1. 启动PostgreSQL
在宝塔面板点击”数据库”，选择”PostgreSQL管理器”：
1. 点击”启动”按钮启动PostgreSQL服务
2. 点击”设置”修改配置文件（可选）
### 2. 创建数据库和用户
在终端中执行：
“`bash
# 切换到postgres用户
sudo -u postgres psql
# 在PostgreSQL命令行中执行
CREATE DATABASE kirameku;
CREATE USER kirameku_user WITH PASSWORD ‘your_secure_password’;
GRANT ALL PRIVILEGES ON DATABASE kirameku TO kirameku_user;
\q
“`
—
## 第四步：部署项目
### 1. 创建网站目录
在宝塔面板点击”文件”，进入 `/www/wwwroot` 目录：
1. 点击”新建目录”，创建 `kirameku` 文件夹
2. 进入 `kirameku` 文件夹
### 2. 克隆项目
在终端中执行：
“`bash
cd /www/wwwroot/kirameku
git clone https://github.com/Xinghongia/Kirameku.git
“`
或者在宝塔文件管理器中：
1. 点击”终端”按钮
2. 执行上述命令
### 3. 设置目录权限
在宝塔文件管理器中：
1. 右键点击 `Kirameku` 文件夹
2. 选择”权限”
3. 设置为 `755`，所有者 `www`
—
## 第五步：部署后端（FastAPI）
### 1. 进入后端目录
“`bash
cd /www/wwwroot/kirameku/Kirameku/backend
“`
### 2. 创建Python虚拟环境
“`bash
python3.11 -m venv venv
source venv/bin/activate
“`
### 3. 安装依赖
“`bash
pip install -r requirements.txt
“`
### 4. 配置环境变量
“`bash
cp .env.example .env
vi .env
“`
编辑 `.env` 文件：
“`env
# 数据库配置
DATABASE_URL=postgresql://kirameku_user:your_secure_password@localhost:5432/kirameku
# JWT密钥（生成随机字符串）
SECRET_KEY=your_random_secret_key_here
# 环境
ENVIRONMENT=production
# CORS（前端域名）
CORS_ORIGINS=[“https://yourdomain.com”,”https://admin.yourdomain.com”]
“`
### 5. 初始化数据库
“`bash
alembic upgrade head
“`
### 6. 使用PM2启动后端
在宝塔面板点击”软件商店” -> “PM2管理器”：
1. 点击”添加项目”
2. 填写以下信息：
– **启动文件**: `/www/wwwroot/kirameku/Kirameku/backend/venv/bin/uvicorn`
– **运行目录**: `/www/wwwroot/kirameku/Kirameku/backend`
– **项目名称**: `kirameku-backend`
– **启动参数**: `app.main:app –host 0.0.0.0 –port 8000 –workers 4`
3. 点击”提交”
或者使用命令行：
“`bash
cd /www/wwwroot/kirameku/Kirameku/backend
source venv/bin/activate
pm2 start “uvicorn app.main:app –host 0.0.0.0 –port 8000 –workers 4” –name kirameku-backend
pm2 save
“`
—
## 第六步：部署前端（Next.js）
### 1. 进入前端目录
“`bash
cd /www/wwwroot/kirameku/Kirameku/frontend
“`
### 2. 安装pnpm
“`bash
npm install -g pnpm
“`
### 3. 安装依赖
“`bash
pnpm install
“`
### 4. 配置API地址
编辑 `siteConfig.ts`：
“`typescript
export const siteConfig = {
// …其他配置
apiBaseUrl: “https://api.yourdomain.com”, // 后端API地址
// …其他配置
}
“`
### 5. 修改构建配置
编辑 `next.config.ts`：
“`typescript
import type { NextConfig } from “next”;
const nextConfig: NextConfig = {
output: “standalone”, // 使用standalone模式
images: {
unoptimized: true,
},
};
export default nextConfig;
“`
### 6. 构建项目
“`bash
pnpm build
“`
### 7. 使用PM2启动前端
在宝塔PM2管理器中：
1. 点击”添加项目”
2. 填写以下信息：
– **启动文件**: `/usr/bin/pnpm`
– **运行目录**: `/www/wwwroot/kirameku/Kirameku/frontend`
– **项目名称**: `kirameku-frontend`
– **启动参数**: `start`
– **环境变量**: `PORT=3000,NODE_ENV=production`
3. 点击”提交”
或者使用命令行：
“`bash
cd /www/wwwroot/kirameku/Kirameku/frontend
PORT=3000 pm2 start pnpm –name kirameku-frontend — start
pm2 save
“`
—
## 第七步：部署管理面板（Vue）
### 1. 进入管理面板目录
“`bash
cd /www/wwwroot/kirameku/Kirameku/admin
“`
### 2. 安装依赖
“`bash
pnpm install
“`
### 3. 配置API地址
编辑 `.env.production`：
“`env
VITE_API_BASE_URL=https://api.yourdomain.com
“`
### 4. 构建项目
“`bash
pnpm build
“`
构建完成后，会在 `dist` 目录生成静态文件。
—
## 第八步：配置网站和反向代理
### 1. 创建前端网站
在宝塔面板点击”网站” -> “添加站点”：
– **域名**: `yourdomain.com` 和 `www.yourdomain.com`
– **根目录**: `/www/wwwroot/kirameku/Kirameku/frontend`
– **PHP版本**: 纯静态
– **SSL**: 可以申请Let’s Encrypt证书
### 2. 配置前端反向代理
点击刚创建的网站 -> “设置” -> “反向代理”：
1. 点击”添加反向代理”
2. 填写：
– **代理名称**: `frontend`
– **目标URL**: `http://127.0.0.1:3000`
– **发送域名**: `$host`
3. 点击”提交”
### 3. 创建API网站
再次点击”添加站点”：
– **域名**: `api.yourdomain.com`
– **根目录**: `/www/wwwroot/kirameku/Kirameku/backend`
– **PHP版本**: 纯静态
### 4. 配置API反向代理
点击API网站 -> “设置” -> “反向代理”：
1. 点击”添加反向代理”
2. 填写：
– **代理名称**: `backend`
– **目标URL**: `http://127.0.0.1:8000`
– **发送域名**: `$host`
3. 点击”提交”
### 5. 创建管理面板网站
点击”添加站点”：
– **域名**: `admin.yourdomain.com`
– **根目录**: `/www/wwwroot/kirameku/Kirameku/admin/dist`
– **PHP版本**: 纯静态
管理面板是静态文件，Nginx直接服务即可，无需反向代理。
—
## 第九步：配置SSL证书
### 1. 申请Let’s Encrypt证书
对于每个网站（前端、API、管理面板）：
1. 点击网站 -> “设置” -> “SSL”
2. 选择”Let’s Encrypt”
3. 勾选域名，点击”申请”
4. 开启”强制HTTPS”
### 2. 自动续签
宝塔会自动处理证书续签，无需手动操作。
—
## 第十步：配置防火墙
### 1. 宝塔防火墙
在宝塔面板点击”安全”：
1. 放行以下端口：
– `22` – SSH
– `80` – HTTP
– `443` – HTTPS
– `8888` – 宝塔面板
– `8000` – 后端API（可选，如果通过Nginx代理可不开放）
– `3000` – 前端服务（可选，如果通过Nginx代理可不开放）
2. 点击”添加规则”，填写端口和备注
### 2. 系统防火墙
在终端中：
“`bash
# 如果使用firewalld
firewall-cmd –permanent –add-service=http
firewall-cmd –permanent –add-service=https
firewall-cmd –reload
# 如果使用ufw
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
“`
—
## 第十一步：部署Reader-Master（可选）
### 1. 进入目录
“`bash
cd /www/wwwroot/kirameku/Kirameku/reader-master
“`
### 2. 编译
“`bash
./gradlew build
“`
### 3. 使用PM2启动
在宝塔PM2管理器中：
1. 点击”添加项目”
2. 填写：
– **启动文件**: `/usr/bin/java`
– **运行目录**: `/www/wwwroot/kirameku/Kirameku/reader-master`
– **项目名称**: `kirameku-reader`
– **启动参数**: `-jar build/libs/reader-master.jar`
—
## 第十二步：设置开机自启
### 1. PM2开机自启
在终端中执行：
“`bash
pm2 startup
pm2 save
“`
### 2. PostgreSQL开机自启
在宝塔面板”软件商店”中，找到PostgreSQL，点击”设置” -> “服务” -> “开机启动”
—
## 常用操作
### 查看日志
在宝塔面板：
– **PM2日志**: 软件商店 -> PM2管理器 -> 点击项目 -> “日志”
– **Nginx日志**: 网站 -> 点击网站 -> “日志”
– **系统日志**: 面板左侧”日志”
### 重启服务
在宝塔面板：
– **重启后端**: PM2管理器 -> 找到kirameku-backend -> “重启”
– **重启前端**: PM2管理器 -> 找到kirameku-frontend -> “重启”
– **重启Nginx**: 软件商店 -> Nginx -> “重启”
### 备份数据库
在宝塔面板：
1. 点击”数据库”
2. 找到kirameku数据库
3. 点击”备份” -> “备份数据库”
4. 可以设置”自动备份”
### 更新代码
“`bash
cd /www/wwwroot/kirameku/Kirameku
git pull
# 更新后端
cd backend
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head
pm2 restart kirameku-backend
# 更新前端
cd ../frontend
pnpm install
pnpm build
pm2 restart kirameku-frontend
# 更新管理面板
cd ../admin
pnpm install
pnpm build
# 无需重启，Nginx直接服务静态文件
“`
—
## 故障排查
### 1. 后端无法启动
在宝塔PM2管理器中查看日志：
– 检查数据库连接配置
– 检查端口8000是否被占用
– 检查Python虚拟环境是否激活
### 2. 前端构建失败
在终端中执行：
“`bash
cd /www/wwwroot/kirameku/Kirameku/frontend
rm -rf node_modules .next
pnpm install
pnpm build
“`
### 3. 502 Bad Gateway
1. 检查后端服务是否运行（PM2管理器）
2. 检查Nginx反向代理配置
3. 检查防火墙端口
### 4. 数据库连接失败
在宝塔面板：
1. 检查PostgreSQL是否启动
2. 检查数据库用户名密码
3. 检查数据库权限
—
## 完成
现在访问以下地址：
– **博客前台**: https://yourdomain.com
– **API文档**: https://api.yourdomain.com/docs
– **管理面板**: https://admin.yourdomain.com
首次访问管理面板时，使用默认账号登录并在后台创建新用户。
—
## 宝塔面板特色功能
### 1. 可视化文件管理
– 在线编辑代码
– 上传下载文件
– 压缩解压
### 2. 数据库管理
– 可视化操作PostgreSQL
– 自动备份
– 导入导出
### 3. 监控告警
– 系统资源监控
– 网站访问统计
– 异常告警
### 4. 一键SSL
– 自动申请Let’s Encrypt
– 自动续签
– 强制HTTPS
### 5. 安全防护
– 防CC攻击
– 防SQL注入
– IP黑白名单
暂无评论内容