logo
paimon/public/BackEnd
Public
0
0
WeChat Login
CodeIssues
1
Pull requestsEventsPackagesInsights
lastest
BackEnd/README.md
Paimon
chore: 代码风格规范化后续清理
bb90de7c

Ink Flow

基于 FastAPI 的博客后端，带 C 扩展加速和 Go 迁移版本。

技术栈

类别技术
后端Python >=3.11, <3.15, FastAPI, SQLAlchemy, Uvicorn
前端Next.js, TypeScript
数据库SQLite (SQLAlchemy)
AI 集成GLM (智谱) + Qwen (通义千问), OpenAI SDK 转发
安全JWT, RSA 加密, Argon2 密码哈希, 权限中间件, 速率限制
监控Prometheus 指标, 远程日志服务
缓存多级内存缓存 (LRU + TTL)
静态站点Hexo 迁移, 自定义 SSG, 静态导出器
构建Poetry, GCC/Make (C 扩展)
可选Go 1.21+ Gin (实验性迁移), PySide6 (桌面端)

项目结构

<project_root>/
├── src/                              # Python FastAPI 后端
│   ├── FastNextAppBackEnd.py         # 应用入口
│   ├── FastNextAppLifeSpan.py        # 生命周期管理 (启动/关闭)
│   ├── FastNextAppDatabase.py        # 数据库会话与建表
│   ├── models/                       # SQLAlchemy 数据模型
│   │   ├── user.py                   # 用户模型
│   │   ├── content.py                # 内容模型
│   │   ├── stats.py                  # 统计模型
│   │   └── file.py                   # 文件模型
│   ├── services/                     # 业务服务层
│   │   ├── content_service.py        # 内容管理服务
│   │   ├── user_service.py           # 用户服务
│   │   ├── stats_service.py          # 统计服务
│   │   ├── archive_service.py        # 归档服务
│   │   ├── file_monitor_service.py   # 文件同步服务
│   │   ├── backup_service.py         # 自动备份
│   │   ├── post_push_service.py      # Post 推送服务
│   │   ├── glm_service/              # AI 模型服务
│   │   └── couch_service/            # CouchDB/Obsidian 服务
│   ├── nextjs_router/                # 路由层
│   │   ├── api/                      # REST API 接口
│   │   ├── client.py                 # 用户客户端路由
│   │   ├── auth.py                   # 认证路由
│   │   ├── control.py                # 控制面板
│   │   ├── ssg.py                    # 静态站点生成
│   │   └── comm.py                   # 通用路由
│   ├── middleware/                   # 中间件
│   │   ├── auth_middleware.py        # 权限验证
│   │   ├── rate_limit.py             # 速率限制
│   │   └── prometheus_metrics.py     # 监控指标
│   ├── utils/                        # 工具层
│   │   ├── static_exporter.py        # 静态站点导出
│   │   ├── content_importer.py       # 内容导入
│   │   ├── slug.py                   # slug 生成
│   │   ├── snapshot_build.py         # API 快照构建 (CLI 入口)
│   │   ├── snapshot_transform.py     # 快照格式转换
│   │   ├── nginx_manager.py          # Nginx 进程管理
│   │   └── cache_manager.py          # 缓存管理
│   └── log_utils/                    # 日志工具
├── src_go/                           # Go Gin 版本 (实验性)
├── lib_c/                            # C 扩展加速模块
│   ├── loader.py                     # 统一加载器 + c_or_py 装饰器
│   ├── c_*.c                         # C 源码 (7 个模块)
│   ├── *_wrapper.py                  # Python wrapper (含降级)
│   └── libs/                         # 编译产物 (.so/.dll)
├── lib/                              # 公共库 (Jinja2 模板等)
├── resource/                         # 静态资源
├── setup/                            # 部署配置 (systemd)
├── pyproject.toml                    # Poetry 依赖配置
├── configs.json                      # 配置模板 (占位符)
└── .config.prod                      # 生产环境配置 (实际值)

核心功能

内容管理 (CMS)

  • Markdown 博客渲染与预览
  • PDF 文档阅读与生成
  • 内容索引与搜索
  • 评论系统 (支持点赞)
  • 侧边栏配置 (公告 / 音乐播放列表)
  • 文件监控与自动同步 (10 分钟周期)

AI 辅助写作 (GLM + Qwen 双通道)

  • GLM 模型集成 (智谱 AI)
  • Qwen 模型集成 (通义千问)
  • 自建 GLMService 服务端 (OpenAI SDK 兼容协议)
  • 免费模型自动检测 (free_models_finder)
  • 流式对话支持 (SSE)

静态站点导出

将整个网站导出为纯静态 HTML 文件，可用于无后端的静态托管。

激活方式: 在 configs.json 中设置 STATIC_EXPORT.ENABLED: true，应用启动时 FastNextAppLifeSpan.startup() 会自动调用 StaticSiteExporter.export_all()。

组件架构:

组件文件职责
StaticSiteExporterstatic_exporter.py主引擎，协调所有组件
URLDiscoverystatic_exporter_url_discovery.py从路由/模板发现 URL
ContentFetchercontent_fetcher.py抓取页面 HTML + 下载静态资源
APIMockerapi_mocker.py生成 API mock 数据 + 正则匹配规则
SEOGeneratorstatic_exporter_seo_generator.py生成 sitemap/robots.txt 等

API 兼容机制 (页面注入 <script> 实现):

  • window.__staticApiData: 精确匹配的 mock JSON 数据 (30+ 端点)
  • window.__staticApiPatterns: 正则模式匹配规则 (14 条，覆盖动态路径)
  • 4 级匹配链：精确匹配 → 去参匹配 → 前缀匹配 → 正则模式匹配
  • SSE 端点返回空 ReadableStream，避免前端解析异常
  • 同时拦截 window.fetch 和 XMLHttpRequest (兼容 axios)

API 快照导出

全量 API 数据快照，支持两种输出格式:

  • 路径镜像 (mirror): 每个端点独立 JSON 文件，nginx 可直接 serve
  • 单文件合并 (merged): 一个 full_snapshot.json，按 endpoint 路径为 key

三阶段执行: 静态端点 → 参数化端点 (自动提取文章 ID/slug/年份/标签) → 写入文件

# CLI 独立运行
python -m src.utils.snapshot_build -o .cnb.build/snapshot -f mirror,merged

# 运行时 API 触发
Invoke-WebRequest -Uri "http://127.0.0.1:30026/api/v1/control/snapshot" `
    -Method POST -Headers @{"Authorization" = "Bearer <admin_token>"; "Content-Type" = "application/json"} `
    -Body '{"formats": ["mirror", "merged"]}'

快照转换: snapshot_transform.py 将 merged 格式拆分为前端可消费的路由级 JSON 目录，旧快照自动清理 (保留最近 5 个目录)。

示例数据库 (resource/examples.db)

项目内置示例数据库，包含完整演示数据:

数据数量
文章63 篇 (前端/后端/DevOps/数据科学/随笔)
用户3 个 (管理员/普通用户/访客)
分类6 个 (含父子关系)
评论80+ 条 (含回复链)
点赞100+ 条
统计数据30 天 (PV/UV/内容/用户)

随机种子固定为 SEED=42，每次构建结果一致。

用户认证与权限

  • 用户注册/登录 (用户名 / 邮箱)
  • Session 管理 (Starlette Session, 14 天有效期)
  • 基于角色的权限控制 (Admin / User / Guest)
  • RSA 密钥自动生成
  • Argon2 密码哈希
  • 速率限制保护 (IP + 用户双维度)

系统监控

  • Prometheus 指标 (/metrics)
  • 远程日志服务 (WebSocket)
  • 自动备份服务
  • 文件同步定时任务
  • 启动时全站内容扫描

RSS 与订阅

  • RSS 2.0 Feed (/feed.xml)
  • Sitemap 生成 (/sitemap.xml)
  • robots.txt

C 扩展加速 (lib_c/)

通过 C 扩展加速关键计算路径，采用统一加载器 + c_or_py 装饰器自动降级。

模块C 源码功能降级支持
content_utilsc_content_utils.c内容处理、字数统计有
similarityc_similarity.c文本相似度计算有
hash_utilsc_hash.c哈希计算 (Keccak)有
toc_parserc_toc_parser.cMarkdown 目录解析有
log_readerc_log_reader.c日志读取有
hexo_utilsc_hexo_utils.cHexo 迁移工具有
fastutilsc_fastutils.c路径处理无
activationc_active_fui.c激活码生成无

使用方式

from lib_c.loader import load_lib, c_or_py

# 加载动态库 (自动查找 .so/.dll)
_lib = load_lib("content_utils")

# c_or_py 装饰器: C 可用时走 C，否则自动降级 Python
@c_or_py(fallback_fn=_word_count_py)
def word_count(text: str) -> int:
    return _lib.cu_word_count(text.encode('utf-8'))

# 调用端直接使用，无需关心底层实现
from lib_c.content_utils import word_count
count = word_count(markdown_text)

编译

cd lib_c && make clean && make

配置系统

configs.json 使用占位符系统，启动时由 lib/settingRenderCI.py 从 .config.prod 读取实际值并注入环境变量。

占位符说明
{BASE_DIR}项目根目录
{RES_DIR}资源目录 (resource/)
{WEB_PORT}服务端口
{FRONT_PATH}前端项目路径
{SMTP_*}邮件服务配置
{ADMIN_REGISTER_KEY}管理员注册密钥
{ZHIPU_API_KEY}智谱 AI API 密钥
{HEXO_PATH}Hexo 博客源目录
{SITE_URL}站点域名

快速开始

环境要求

  • Python 3.11+
  • Poetry (依赖管理)
  • GCC/Make (编译 C 扩展, 可选)

安装与运行

git clone https://cnb.cool/paimon/public/BackEnd.git
cd BackEnd

poetry install

# 编译 C 扩展 (推荐)
cd lib_c && make && cd ..

# 创建生产配置
cp .config.prod.example .config.prod
# 编辑 .config.prod 填入实际值

poetry run uvicorn src.FastNextAppBackEnd:app --host 0.0.0.0 --port 30026

部署

方式一：CNB 一键部署（推荐）

项目内置完整的 CI/CD 管线，通过 CNB 平台一键完成从代码到运行的全流程。

按钮功能触发条件
部署到生产环境完整构建：Poetry 安装 -> C 编译 -> 启动服务 -> API 快照导出正式上线
导出 API 快照仅执行 snapshot_build 导出全量 JSON 到 .cnb.build/snapshot/数据更新后
编译 C 模块仅编译 lib_c/ 并推送 .so 文件（[skip ci] 不触发完整构建）C 源码变更
重启服务停止旧进程、重新启动 uvicorn配置变更
清理缓存清理 Poetry 缓存和 .venv/构建异常时
快速预览Python 语法检查 + Poetry 配置校验提交前验证

部署流程详情：

# 以下步骤由 CNB 自动执行，手动部署可参考

# 1. 环境准备
apt-get install -y gcc make curl
curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"

# 2. 配置镜像源（国内加速）
poetry config repositories.tsinghua https://pypi.tuna.tsinghua.edu.cn/simple
poetry config repositories.aliyun https://mirrors.aliyun.com/pypi/simple/
poetry config repositories.tencent https://mirrors.cloud.tencent.com/pypi/simple/

# 3. 安装依赖（多源自动切换）
poetry install --no-interaction --no-root --only main || \
poetry install --no-interaction --no-root --only main --source tsinghua || \
poetry install --no-interaction --no-root --only main --source aliyun || \
poetry install --no-interaction --no-root --only main --source tencent

# 4. 编译 C 扩展
cd lib_c && make clean && make && cd ..

# 5. 创建运行目录
mkdir -p src/instance resource/_posts resource/static

# 6. API 快照导出
python -m src.utils.snapshot_build -o .cnb.build/snapshot -f mirror,merged

# 7. 启动服务
poetry run python -m uvicorn src.FastNextAppBackEnd:app \
    --host 0.0.0.0 --port 30026 > backend.log 2>&1 &

环境变量（CNB 构建时可设置）：

变量说明默认值
ADMIN_KEY管理员注册密钥无
SKIP_TESTS是否跳过测试false
CNB_TRIGGER_TOKEN触发前端部署令牌无

方式二：手动部署

适用于本地服务器或非 CNB 环境。

# 1. 克隆项目
git clone <repo_url> && cd BackEnd

# 2. 安装 Python 3.11+ 和 Poetry
# Ubuntu/Debian:
sudo apt-get update && sudo apt-get install -y python3.11 python3-pip gcc make
pip3 install poetry
# macOS:
brew install python@3.11 poetry

# 3. 安装依赖
poetry install

# 4. 编译 C 扩展（可选但推荐）
cd lib_c && make && cd ..

# 5. 初始化配置
cp .config.prod.example .config.prod
# 编辑 .config.prod 填入实际值（数据库路径、端口、密钥等）

# 6. 构建示例数据库（可选）
python -m src.utils.db.build_examples_db --output resource/examples.db

# 7. 导出 API 快照（静态站点模式需要）
python -m src.utils.snapshot_build -o .cnb.build/snapshot -f mirror,merged

# 8. 启动服务
poetry run uvicorn src.FastNextAppBackEnd:app --host 0.0.0.0 --port 30026

方式三：systemd 服务（长期运行）

# 1. 注册服务
sudo cp setup/fastapp.service /etc/systemd/system/
sudo systemctl daemon-reload

# 2. 开机自启并启动
sudo systemctl enable fastapp
sudo systemctl start fastapp

# 3. 常用操作
sudo journalctl -u fastapp -f          # 实时查看日志
sudo systemctl restart fastapp         # 重启
sudo systemctl status fastapp           # 状态检查
netstat -tlnp | grep 30026             # 确认端口监听

# 4. 定时重启（可选，每周日凌晨 4 点）
sudo tee /etc/cron.d/fastapp-restart <<'EOF'
0 4 * * 0 root systemctl restart fastapp
EOF

API 快照导出

快照将所有 API 端点的返回数据导出为静态 JSON，供前端静态页面消费。

# CLI 独立运行（两种格式可选或同时使用）
python -m src.utils.snapshot_build -o .cnb.build/snapshot -f mirror,merged

# 仅 mirror 格式（按端点路径分文件，适合 nginx 直接 serve）
python -m src.utils.snapshot_build -o output/mirror -f mirror

# 仅 merged 格式（单个 full_snapshot.json）
python -m src.utils.snapshot_build -o output/merged -f merged

# 运行中通过 API 触发（需认证）
curl -X POST http://127.0.0.1:30026/api/v1/control/snapshot \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"formats": ["mirror", "merged"]}'

# 输出结构
# .cnb.build/snapshot/
# ├── manifest.json              # 元信息（端点列表、错误统计）
# ├── full_snapshot.json         # 合并格式
# ├── snapshot_20260404_120000/   # 按时间戳的独立目录
# │   ├── api/v1/info/...        # mirror 格式的路径镜像
# │   └── ...
# └── snapshot_latest -> snapshot_20260404_120000  # 最新快照软链接

Nginx 管理

项目内置跨平台 Nginx 进程管理器 (nginx_manager.py)，支持 Linux / Windows。

自动管理：应用启动时 FastNextAppLifeSpan 会自动：

  • 检测已有 Nginx 进程，避免重复启动
  • 每 60 秒检测配置文件变更（md5 hash），变更时自动 reload

手动部署 Nginx 配置：

# 使用内置工具一键部署到系统默认位置（带备份）
python -m src.utils.dev.openconf \
    template=nginx.conf.template platform=linux \
    output=/etc/nginx/conf.d/fastapp.conf backup=True

# 或生成到自定义位置查看
python -m src.utils.dev.openconf platform=linux output=./openconf/nginx.linux.conf
python -m src.utils.dev.openconf platform=windows output=./openconf/nginx.windows.conf

Nginx 配置要点：

# 反向代理到 FastAPI
location /api/ {
    proxy_pass http://127.0.0.1:30026;
    # 关键：透传 Cookie（Session 依赖）
    proxy_set_header Cookie $http_cookie;
}

# 静态资源（含 API 快照的 mirror 格式）
location ~ ^/(static|_next)/ {
    alias /path/to/resource/;
}

# 注意：alias 末尾必须带斜杠
location /_export_html/ {
    alias /path/to/resource/_export_html/;
}

故障排查

# Poetry 相关
poetry cache clear --all --no-interaction   # 清理缓存重试
poetry install --no-interaction --no-root     # 重新安装依赖

# C 扩展编译失败
apt-get install -y gcc make                  # 确认系统工具链
cd lib_c && make clean && make               # 清理后重编

# 服务启动失败
cat backend.log                               # 查看 nohup 日志
journalctl -u fastapp -n 50                  # systemd 日志
poetry run python -c "from src.FastNextAppBackEnd import app; print('OK')"  # 导入检查

# 端口被占用
lsof -i :30026                                # 查看占用进程
kill -9 <PID>                                # 终止占用

# 权限问题
chmod -R 755 src/instance                    # 运行目录权限
chown -R www-data:www-data resource/         # Nginx 可读资源

Go 版本 (实验性)

src_go/ 目录包含从 Python FastAPI 到 Go Gin 的迁移版本，覆盖核心路由和模型。

详见 src_go/README.md，包含完整的 Python -> Go 模型和路由映射表。

开发规范

项目遵循 paimon1999原则:

  • 不使用装饰性注释和分隔符
  • 注释解释"为什么"而非"做什么"
  • 注释频率控制在每 20-50 行 0-1 条
  • C 扩展 wrapper 使用 loader.py 统一加载
  • 调用端不包含降级逻辑 (通过 c_or_py 装饰器自动处理)

更新日志

v1.0.0 (2026-04-04)

首次正式发布:

  • 全栈博客 CMS: 内容管理、评论、侧边栏配置
  • AI 双通道写作辅助 (GLM + Qwen, OpenAI SDK 协议)
  • 静态站点导出引擎 (URL 发现 + 并发抓取 + SEO 生成)
  • API 快照管线 (mirror/merged 双格式, 三阶段写入)
  • C/Python 透明双轨架构 (8 个 C 扩展模块, 自动降级)
  • 多级缓存体系 (LRU + TTL, 分区管理)
  • TF-IDF 相似度引擎 (零外部 NLP 依赖, 含 C 加速版)
  • 拓扑排序数据库导入 (Kahn 算法保证外键依赖顺序)
  • 纯 ASGI 中间件 (速率限制/认证/Prometheus 全原生)
  • Nginx 进程管理器 (跨平台, 配置变更自动 reload)
  • Git 自动同步定时任务
  • 示例数据库 (63 篇文章, 种子固定可复现)
  • 代码风格全面规范化

许可证

Apache-2.0

© 2026 Tencent, Inc. Supported by Tencent Cloud
About Us
Privacy Policy
Terms of Service
SLA
API
Docs
Showcase
Feedback
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
京ICP备11018762号-111
粤公网安备44030002006058号粤公网安备44030002006058号