01项目概述
这是一个从域名选型、UI/UX 交互设计、Astro 5 前端架构、Python 异步后端到云端生产运维全部独立完成的全栈技术作品集。核心设计理念是极致性能（0 白屏）、无缝交互（Fluid SPA Transition）与专业严谨的工程落地。
全站摒弃笨重的第三方 UI 模板，核心动效引擎、双主题感知色彩、每一个接口逻辑与 Nginx 反向代理配置皆为手工打磨；边缘侧接入 Cloudflare，源站 IP 隐身、静态资源全球边缘缓存。
Cloudflare 边缘加速层
静态资源就近边缘缓存（实测 HIT），源站 IP 全网隐身，WAF 与 DDoS 防护免费加持
黑金开屏加载动画
金色圆环描边 + 「月」字压印 + 进度线，幕布上提退场；会话内仅出现一次，可点击跳过
Astro 5 + ClientRouter
无缝 SPA 流体路由，零白屏瞬时响应，顶部 Turbo Top Loader 极速光感反馈
OKLCH 双主题色彩系统
全域感知均匀色彩，日间模式 Apple/Linear 质感重塑，暗色模式微光通透
GSAP 卡片堆叠 + Bento Grid
物理弹性卡片堆叠（Stacking Cards），3 列非对称科技便当盒网格布局
Before/After 交互对比滑块
自研纯 CSS/JS 图像对比引擎，支持触控拖拽与多波段 GPU 硬件渲染展示
FastAPI 异步微服务后端
Python 3.12 异步驱动，23 个 RESTful 端点，Cookie SHA-256 认证与内存防刷
DeepSeek 驱动的站内 AI 助手
前台简历问答 + 后台 Hermes 交互，DeepSeek 官方模型直连，关闭思考链保证毫秒级响应
02系统架构全景
用户浏览器 / 移动端
│ HTTPS
▼
┌───────────────────────────────────────────────┐
│ Cloudflare 边缘网络（全球 Anycast 节点） │
│ 静态资源边缘缓存 · WAF · DDoS 防护 │
│ Universal SSL · 源站 IP 隐身 · 真实 IP 回传 │
└──────────────────────┬────────────────────────┘
│ 仅动态请求回源
▼
┌───────────────────────────────────────────────┐
│ Nginx 源站（80/443）反向代理 + 静态分发 │
│ Let's Encrypt · HTTP/2 · Gzip · realip 模块 │
└──────────────┬────────────────────────────────┘
│
┌───────┴────────────────┐
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ Astro 5 SSG 前端 │ │ FastAPI 异步后端 │
│ 21 页面 · 流体路由 │ │ Uvicorn (:8000) │
│ 开屏动画 · GSAP 动效 │ │ 23 端点 · 内存限流 │
└──────────────────────┘ └───────────┬──────────┘
│
┌────────────┴────────────┐
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ SQLite 单文件数据库 │ │ Hermes AI Agent │
│ 访问日志·文章·留言 │ │ DeepSeek 官方模型 │
└──────────────────────┘ └──────────────────────┘
03技术栈全景
🚀
前端框架
Astro 5 (SSG 静态生成)
ClientRouter 流体路由
Vue 3 响应式岛屿
🎨
视觉与排版
OKLCH 色彩空间 · Design Tokens
思源宋体子集自托管
双主题无缝平滑切换
✨
交互动效
GSAP 3.12 + ScrollTrigger
物理弹性卡片堆叠
开屏印章动画 · 图像对比滑块
🐍
后端核心
FastAPI + Uvicorn
Python 3.12 异步并发
23 个端点 · 内存限流
🗄️
嵌入式数据库
SQLite 单文件数据源
4 张核心表 · 零运维开销
访问日志/文章/文件/留言
🌐
边缘加速与防护
Cloudflare Anycast 边缘缓存
WAF · DDoS · Universal SSL
源站 IP 隐身 · 真实 IP 回传
🔒
反向代理与安全
Nginx 1.24 · Let's Encrypt HTTPS
HTTP/2 · Gzip · immutable 缓存头
fail2ban 防爆破 · 密钥登录
📱
响应式与无障碍
Fluid 响应式系统
移动端分类吸顶胶囊导航
prefers-reduced-motion 降级
🤖
AI 智能助理
Hermes Agent + DeepSeek 官方
飞书 WebSocket 长连接
HMAC-SHA256 回调校验
📦
持续集成与部署
Git + GitHub Actions
astro 分支构建 → main 产物
systemd 守护 · Crontab 自动同步
04核心功能与交互创新
1. Astro 5 ClientRouter 流体路由与 Turbo Loader
全站采用 Astro 5 硬件加速的 <ClientRouter /> 架构接管路由，消除传统静态网站多页面切换时的白屏与生硬闪烁。页面跳转时辅以 2.5px 顶部紫金流光加载进度条（Turbo Top Loader） 与 物理弹性平滑滑动（Slide & Fade），让多页面静态站点拥有丝滑单页 Web App 的极速触感。
2. 3 列非对称 Bento Grid（便当盒网格布局）
专题项目区域采用 3 列非对称 Bento Grid 设计：核心亮点项目（如 ComfyUI AI 艺术画廊、CartoonCGAN 动漫风格迁移）跨越 2 列大卡展示，次要工具与实用项目采用 1 列紧凑卡片。打破常规列表的单调感，构建主次分明的视觉节奏。
3. Before / After 交互式图像对比引擎
在 AI 图像处理与风格迁移项目详情中，自研了轻量级、零外部依赖的交互对比滑块组件（ImageCompare.astro）。利用 CSS 变量 --pos 与硬件加速 clip-path: polygon()，支持鼠标拖拽、手势滑动、发光中线拉手与磨砂玻璃角标，直观展示真机实测前后的细节对比。
4. 移动端极致交互优化
分类吸顶胶囊导航（Sticky Tab Bar）
移动端专属 4 模块分类胶囊，随滚动双向高亮同步，点击平滑直达对应项目分区
沉浸式图片大图灯箱（Lightbox）
全站图表、架构图、界面截图支持一键全屏放大预览，支持 ESC 键与手势关闭
代码块一键复制与智能语言标识
自动解析 Prism/Shiki 代码块类型，右上角悬浮一键复制按钮与反馈动效
5. 黑金开屏加载动画（Splash）
首次进入站点时呈现的定制开屏：金色圆环以 stroke-dashoffset 描边展开，「月」字印章式压印浮现，随后进度线填充、幕布以 clip-path 上提揭幕。全流程纯 CSS 合成层实现，无图片、无额外请求。
工程上做了三处克制：会话内只出现一次（sessionStorage 标记，内部路由跳转绝不重复）；资源就绪即走但设有最短展示时长（移动端 2.0s / 桌面 1.65s），避免移动端缓存命中时一闪而过；三重兜底（JS 4.2s 硬超时 + CSS 4.8s 强制淡出 + 内联脚本 5.2s 摘遮罩）确保任何环节异常都不会把人锁在遮罩里。同时尊重 prefers-reduced-motion，点击或 Esc 可跳过。
05后端接口与微服务架构
FastAPI 共提供 23 个端点（含 1 个后台页面路由），下表列出核心业务接口：
| 方法 | 路径 | 功能 | 认证机制 |
|---|
| POST | /api/analytics/hit | 前端无感访问数据上报 | 公开 |
| GET | /api/analytics/summary | PV / UV / 热门页面分析统计 | 公开 |
| GET | /api/articles | 博客文章发布列表检索 | 公开 |
| GET | /api/articles/{slug} | 文章 Markdown 详情获取 | 公开 |
| POST | /api/contact | 联系表单提交（带 IP 内存限流） | 公开（限流） |
| POST | /api/chat/assistant | 站内 AI 简历问答（DeepSeek 驱动） | 公开（限流） |
| POST | /api/admin/login | 后台管理登录鉴权 | 密码 |
| GET | /api/admin/session | 登录态校验与续期 | Cookie (HttpOnly) |
| GET / POST | /api/admin/articles | 文章创建、发布与管理 | Cookie (HttpOnly) |
| PUT / DELETE | /api/admin/articles/{id} | 文章动态编辑与物理删除 | Cookie (HttpOnly) |
| POST | /api/admin/upload | 大文件分片/直传（支持 200MB） | Cookie (HttpOnly) |
| GET | /api/admin/files | 服务器资源文件列表查询 | Cookie (HttpOnly) |
| GET | /api/admin/contacts | 访客留言实时查看与审核 | Cookie (HttpOnly) |
| POST | /api/admin/hermes | Hermes AI 助手交互调用 | Cookie (HttpOnly) |
| POST | /api/hermes/callback | Hermes 异步回调（人工回复回流） | HMAC-SHA256 |
06安全工程与 SEO 优化
🛡️
无感防御
基于真实客户端 IP 的内存限流
Cloudflare 真实 IP 回传还原
登录失败熔断 · 留言防刷机制
🔐
安全鉴权
Cookie Token · SHA-256 加盐哈希
HttpOnly · SameSite · Secure
密钥从环境变量注入，不落盘
🧼
XSS 纵深防御
后台所有动态值强制 esc() 转义
匿名写入接口限长与类型校验
XSS 回归测试用例守护
📁
文件保护
MIME 类型严格白名单
UUID 重命名 · 隔离存储
200MB 体积上限
🔑
主机层加固
fail2ban 自动封禁爆破 IP
ed25519 密钥登录
非标准端口运维通道
🔍
结构化 SEO
Schema.org Person / CreativeWork
OpenGraph · Twitter Cards · Sitemap
♿
无障碍标准
语义化 HTML5 标签体系
全站 WCAG AAA 级对比度适配
⚡
极限性能
静态预编译 · 图片 WebP / 异步解码
自托管字体子集 · 边缘缓存 HIT
07生产部署与运维拓扑
| 部署维度 | 具体配置与技术实现 |
|---|
| 云服务器 | 阿里云轻量应用服务器（Ubuntu 24.04.2 LTS · 2vCPU / 2GB RAM / 40GB ESSD） |
| 域名与 DNS | qtxingyue.me（Namecheap 注册 · Cloudflare 托管解析并开启橙云代理） |
| 边缘加速 | Cloudflare Anycast 网络：静态资源边缘缓存（cf-cache-status: HIT）、WAF、DDoS 防护、源站 IP 隐身 |
| SSL 证书 | Cloudflare Universal SSL（边缘）+ Let's Encrypt（回源），Full (Strict) 校验模式 |
| 服务守护 | systemd 管理（sakura-backend / hermes-gateway），异常自动重启 |
| 静态资源策略 | Nginx 直出 + Cache-Control immutable → Cloudflare 边缘缓存，HTML 强制 no-cache 保持实时 |
| 自动化流程 | Git push origin astro → GitHub Actions 自动编译并推 main → 服务器 Crontab 每分钟 fetch + reset |
| 主机安全 | fail2ban（sshd jail，10 分钟 5 次失败即封禁，递增至 1 周）+ ed25519 密钥 + 阿里云安全组 |
| 真实 IP 还原 | Nginx realip 模块 + Cloudflare IP 段白名单，限流与日志始终基于真实访客 IP |