161 lines
8.1 KiB
Markdown
161 lines
8.1 KiB
Markdown
# 孤竹居士的个人博客
|
||
|
||
部署在阿里云 Ubuntu 上的个人全栈博客系统：原生前端 SPA + FastAPI + SQLite。
|
||
|
||
## 技术架构
|
||
|
||
| 层 | 技术 |
|
||
| --- | --- |
|
||
| 服务器 | Ubuntu Linux + Nginx |
|
||
| 前端 | 原生 HTML + CSS + JavaScript（SPA，History API 路由） |
|
||
| 后端 | Python FastAPI（仅监听 127.0.0.1:8080） |
|
||
| 数据库 | SQLite + SQLAlchemy ORM |
|
||
| 认证 | JWT Token（bcrypt 存储密码哈希） |
|
||
| 文件 | Nginx 静态访问 uploads 目录 |
|
||
|
||
- Nginx：80（HTTP）/ 443（HTTPS，待配置）；`/api/*` 反代到 `127.0.0.1:8080`；`/uploads/*` 静态映射。
|
||
- 端口：22 SSH、80 HTTP、443 HTTPS、25565 Minecraft（独立运行，不占用博客端口）。
|
||
|
||
## 目录结构
|
||
|
||
```text
|
||
blog/
|
||
├── frontend/ # 前端源码（原生 SPA，ES Modules 拆分）
|
||
│ ├── index.html
|
||
│ ├── style.css
|
||
│ ├── main.js # 入口：初始化 + 全局事件
|
||
│ ├── api.js # 网络层：api() / uploadFile()
|
||
│ ├── auth.js # 登录 / 注册 / 会话
|
||
│ ├── router.js # 路由与页面壳（导航栏、用户区）
|
||
│ ├── article.js # 文章列表 / 详情 / 分区 / 简介视图
|
||
│ ├── comment.js # 评论与回复
|
||
│ ├── friend.js # 好友申请
|
||
│ ├── manage.js # 博主管理面板（发文 / 编辑 / 简介设置）
|
||
│ ├── markdown.js # Markdown 轻量渲染（含 URL 白名单）
|
||
│ ├── state.js # 全局常量与状态
|
||
│ └── utils.js # DOM / 日期 / 弹窗 / Toast 工具
|
||
├── backend/
|
||
│ ├── main.py # FastAPI 实例 + 路由注册 + 统一错误格式
|
||
│ ├── database.py # SQLite 连接与初始化
|
||
│ ├── models.py # ORM 模型（User/Article/Comment/Like/Friend/EmailCode）
|
||
│ ├── schemas.py # Pydantic 请求/响应模型
|
||
│ ├── auth.py # bcrypt + JWT + 当前用户依赖
|
||
│ ├── security.py # 邮箱校验、IP 提取、内存限流器
|
||
│ ├── email.py # SMTP 验证码发送
|
||
│ ├── seed.py # 博主账号初始化（python -m backend.seed）
|
||
│ └── routers/ # 业务路由（user/article/comment/like/friend/email/password/upload）
|
||
├── uploads/
|
||
│ ├── avatar/ # 头像
|
||
│ ├── article/ # 文章图片（封面/插图）
|
||
│ └── project/ # 项目文件（zip）
|
||
├── .env # 环境配置（已被 .gitignore 忽略，勿提交）
|
||
├── .env.example # 环境变量模板（全中文注释）
|
||
├── requirements.txt # Python 依赖
|
||
└── README.md
|
||
```
|
||
|
||
## 快速开始（本地开发）
|
||
|
||
1. 安装依赖：`pip install -r requirements.txt`
|
||
2. 配置环境：复制 `.env.example` 为 `.env`，填写 `JWT_SECRET`、`BLOGGER_*`、`SMTP_*`。
|
||
3. 初始化数据库与博主：`python -m backend.seed`
|
||
4. 启动后端：`uvicorn backend.main:app --host 127.0.0.1 --port 8080`
|
||
5. 启动前端：任意静态服务器指向 `frontend/`，并将 `/api/*` 反代到 `127.0.0.1:8080`、`/uploads/*` 映射到 `uploads/`（本地开发可借助 Nginx 或简单代理脚本实现）。
|
||
|
||
> 提示：前端为 SPA，任意路径（如 `/article/1`）都应回退到 `index.html`。
|
||
|
||
## 权限与角色
|
||
|
||
| 角色 | 权限 |
|
||
| --- | --- |
|
||
| visitor（游客） | 查看公开文章、申请好友（好友文章仅显示标题与封面） |
|
||
| friend（好友） | 查看公开与好友文章、评论（含回复）、点赞 |
|
||
| blogger（博主） | 全部权限：发布/编辑/删除文章、审批好友申请、上传图片与项目、修改简介与头像 |
|
||
|
||
## API 一览（统一前缀 `/api`，统一响应 `{success, data, message}`）
|
||
|
||
**认证与资料**
|
||
- `POST /api/register` 注册（邮箱/用户名/密码，bcrypt 存储）
|
||
- `POST /api/login` 登录（JWT；失败限流）
|
||
- `GET /api/user/level` 当前角色
|
||
- `GET /api/user/me` 当前用户资料
|
||
- `GET /api/user/blogger` 博主公开资料（简介页）
|
||
- `PUT /api/user/profile` 更新头像/简介
|
||
|
||
**文章**
|
||
- `POST /api/article/add` 发布（仅博主）
|
||
- `GET /api/article/list?page=&page_size=` 列表（分页；好友文章对游客仅标题+封面）
|
||
- `GET /api/article/{id}` 详情（好友文章对游客锁定正文）
|
||
- `PUT /api/article/{id}` 编辑（仅博主）
|
||
- `DELETE /api/article/{id}` 删除（仅博主，级联评论/点赞）
|
||
|
||
**评论 / 点赞 / 好友**
|
||
- `POST /api/comment/add` 评论或回复（`parent_id` 可选；仅好友/博主）
|
||
- `GET /api/comment/list?article_id=` 评论列表
|
||
- `POST /api/like/add` 点赞（好友/博主，不可重复）
|
||
- `GET /api/like/list?article_id=` 点赞列表
|
||
- `POST /api/friend/apply` 申请好友 / `GET /api/friend/status` 好友状态
|
||
- `GET /api/friend/applications` 申请列表（仅博主）
|
||
- `POST /api/friend/{id}/approve|reject` 审批（仅博主）
|
||
|
||
**邮箱验证码 / 密码**
|
||
- `POST /api/email/send-code` 发送验证码（邮箱+IP 限流）
|
||
- `POST /api/email/verify-code` 校验验证码（尝试次数限制）
|
||
- `POST /api/password/forgot` 忘记密码 / `POST /api/password/reset` 重置密码
|
||
|
||
**上传**
|
||
- `POST /api/upload/avatar` 头像（jpg/png/webp，≤2MB）
|
||
- `POST /api/upload/article` 文章图片（仅博主，≤5MB）
|
||
- `POST /api/upload/project` 项目文件（仅博主，zip，≤50MB）
|
||
|
||
## 安全说明
|
||
|
||
- 密码 bcrypt 哈希存储，禁止明文；localStorage 仅保存 token 与用户名。
|
||
- JWT_SECRET 缺失时后端拒绝启动（fail-fast），禁止硬编码弱密钥。
|
||
- 登录、验证码发送/校验均有内存限流（阈值可在 `.env` 调整）。
|
||
- 上传文件：白名单扩展名 + 魔数校验 + 随机文件名，禁止执行用户上传内容。
|
||
- 前端 Markdown 渲染带 URL 协议白名单（`javascript:`/`data:` 等被拦截）+ CSP 响应头/标签（纵深防御）。
|
||
- 后端仅监听 127.0.0.1:8080，禁止公网直连。
|
||
- 注册接口对“邮箱 / 用户名已占用”返回统一提示，且先核验验证码再查唯一性（防枚举）；注册失败会作废本次验证码，需重新发送后再试。
|
||
|
||
## 部署（阿里云）
|
||
|
||
> 详细的 Nginx 站点配置与 systemd 服务文件将在后续任务中补充（当前仅给出要点）。
|
||
|
||
1. 上传项目到 `/var/www/blog`，安装依赖：`pip install -r requirements.txt`。
|
||
2. 配置 `.env`（强随机 `JWT_SECRET`、博主账号、SMTP、安全限流）。
|
||
3. `python -m backend.seed` 初始化数据库与博主。
|
||
4. Nginx：80 端口托管 `frontend/` 静态文件；`/api/*` 反代 `127.0.0.1:8080`；`/uploads/*` 映射 `uploads/`；SPA 回退 `index.html`。
|
||
5. systemd 守护 `uvicorn`（开机自启、崩溃重启）。
|
||
6. 安全组仅开放 22 / 80 / 443 / 25565。
|
||
|
||
## 数据库升级说明（仅旧库需要）
|
||
|
||
全新部署无需迁移：`python -m backend.seed` 会自动按最新结构建表。
|
||
|
||
若从旧版本升级（服务器上已有 `backend/blog.db`），需先补齐新字段再重启服务：
|
||
|
||
```bash
|
||
# 服务器（Ubuntu）执行；正式升级前建议先备份 backend/blog.db 与 uploads/
|
||
cd /var/www/blog
|
||
python3 - <<'EOF'
|
||
import sqlite3, datetime
|
||
con = sqlite3.connect("backend/blog.db")
|
||
con.execute("ALTER TABLE users ADD COLUMN token_version INTEGER NOT NULL DEFAULT 0")
|
||
con.execute("ALTER TABLE friends ADD COLUMN created_time DATETIME")
|
||
con.execute("ALTER TABLE articles ADD COLUMN category VARCHAR(30) NOT NULL DEFAULT 'life'")
|
||
con.execute("ALTER TABLE users ADD COLUMN avatar_updated_time DATETIME")
|
||
now = datetime.datetime.now(datetime.UTC).replace(tzinfo=None) # 与后端 utcnow() 一致：无时区 UTC
|
||
con.execute("UPDATE friends SET created_time=? WHERE created_time IS NULL", (now,))
|
||
con.commit()
|
||
con.close()
|
||
print("数据库升级完成")
|
||
EOF
|
||
```
|
||
|
||
本地开发（Windows）若仅为调试数据，可省略迁移：删除 `backend/blog.db` 后重新执行 `python -m backend.seed` 即可。
|
||
|
||
字段说明：
|
||
- `users.token_version`：JWT 令牌版本号。重置密码后版本自增，该用户所有旧令牌立即失效（登录状态吊销）。
|
||
- `friends.created_time`：好友申请创建时间，用于博主审批列表展示申请时间。
|