PROJECT 001

凝神全栈

NINGSHEN-FULLSTACK

一个个人作品集/博客网站
一套完整的工程化解决方案

1.1

不仅仅是网站

涵盖开发、测试、构建、部署、运维全生命周期。

STEP 01

开发

前端 + 后端代码
网站的"门面"和"大脑"

STEP 02

测试

代码质量检查
确保无低级错误

STEP 03

构建

Docker 容器化
打包成"集装箱"

★

STEP 04

部署

蓝绿部署
用户无感知更新

STEP 05

运维

监控、日志、告警
第一时间发现

1.2

技术栈

构建这个项目所使用的所有技术工具的集合。

前端技术

用户看到的界面

FRAMEWORK

Nuxt.js 4

支持服务端渲染(SSR)，对搜索引擎友好。基于 Vue.js 的全栈框架。

CORE

Vue 3

学习曲线平缓，生态丰富，国内普及度高。

LANGUAGE

TypeScript

带类型的 JavaScript。能在编码时发现错误，代码更可靠。

STYLE

Tailwind

原子化 CSS 框架。快速编写样式，无需切换文件。

后端技术

FastAPI

Python Web 框架。性能高、自动生成 API 文档。

Python 3.10

语法简单易学，生态完善。

SQLAlchemy

ORM 工具，用 Python 代码操作数据库。

asyncpg

PostgreSQL 异步驱动，支持高并发。

存储 & 基础设施

PostgreSQL 15

CACHE

Redis 7

INFRA

Docker

PROXY

Nginx

CI/CD

GitHub Actions

1.3

线上环境

DOMAINningshen.top

SERVER2C / 2GB / 40GB

REGISTRYAliyun ACR

SSLLet's Encrypt

NOTE:
应用镜像由 CI/CD 构建推送。基础镜像通过 GitHub Actions 中转拉取官方源后推送至 ACR，避免服务器直连 Docker Hub 超时。

CHAPTER 02

系统架构
总览

SYSTEM ARCHITECTURE

2.1

什么是系统架构？

系统架构就像房屋的设计图纸，它定义了：有哪些"房间"（组件）、每个房间做什么用（职责）、房间之间怎么连通（通信）。

2.2

本项目架构风格

本项目采用「模块化单体 + 前后端分离」的架构风格。

STYLE A

全部功能

简单但难扩展

CURRENT PROJECT

STYLE B

前端

后端

适中，易维护 ✅

STYLE C

复杂但高度灵活

为什么选择这种架构？

项目规模个人/小团队项目，无需微服务复杂性

团队规模1-3人，单体更易于开发和调试

部署复杂度希望简单，Docker Compose一键部署

扩展需求中等，前后端分离已足够灵活

2.3

系统架构图

用户请求从发起到响应的完整流程。

🌐

用户

浏览器 / 手机

🔒 NGINX

核心职责

• 接收所有 HTTP/HTTPS 请求
• SSL/TLS 加密解密
• 蓝绿部署流量切换

路由规则

/api/* → FastAPI :8000

/* → Nuxt.js :3000

🎨 前端服务

:3000

Nuxt.js

• 渲染网页界面
• 服务端渲染(SSR)
• 与后端 API 通信

BLUE: :3001 | GREEN: :3002

⚙️ 后端服务

:8000

FastAPI

• 处理业务逻辑
• 数据增删改查
• 用户认证授权

BLUE: :8001 | GREEN: :8002

💾 PostgreSQL

:5432

• 用户信息、文章、评论
• 持久化存储，ACID保证

⚡ Redis

:6379

• 会话数据、缓存
• 内存存储，极快速度

2.4

请求处理流程示例

以「用户访问首页」为例。

用户在浏览器输入 https://ningshen.top

请求发起

DNS 解析域名 → 获得服务器 IP 地址

寻找目的地

建立 HTTPS 连接（SSL/TLS 握手）

安全握手

请求到达 Nginx（端口 443）

Nginx 检查路径：/ → 匹配 /* 规则，决定转发到前端服务

Nginx 转发请求到 Nuxt.js（端口 3000）

执行服务端渲染(SSR)，获取数据，渲染组件为HTML

响应返回用户，浏览器渲染页面 ✅

整个过程通常在 100-500ms 内完成

CHAPTER 03

后端架构
设计

BACKEND ARCHITECTURE

3.1

什么是后端？

后端就是网站的"幕后工作者"。

验证身份

处理请求

读写数据库

返回结果

前端是用户看到的"门面"，后端是处理数据的"大脑"。

3.2

后端应用结构

📁 backend/

│

├── 📄 main.py # 应用入口，启动 FastAPI

│

├── 📁 app/

│ ├── 📄 config.py # 配置管理

│ ├── 📄 database.py # 数据库连接

│ │

│ ├── 📁 models/ # 数据模型

│ │ ├── user.py

│ │ └── article.py

│ │

│ ├── 📁 routers/ # API 路由

│ │ ├── health.py

│ │ └── resume.py

│ │

│ ├── 📁 middleware/ # 中间件

│ └── 📁 utils/ # 工具函数

│

└── 📄 requirements.txt # Python 依赖清单

3.3

分层架构解析

📡 路由层 (Routers)

接收 HTTP 请求，调用处理函数，返回响应

@router.get("/api/v1/health")
async def health_check(): ...

⚙️ 业务逻辑层 (Services)

处理具体业务逻辑：验证、计算、数据转换

类比：餐厅的厨师，根据订单制作菜品

💾 数据访问层 (Models)

与数据库交互，执行增删改查操作

class ResumeDownload(Base):
id = Column(UUID, primary_key=True)

🗄️ 数据库 (PostgreSQL)

存储所有持久化数据

3.4

数据库设计

规划"数据怎么存储"，就像设计一个档案柜。

👤 users (用户表)

🔑 id (UUID) PK

username

password_hash

created_at

📝 articles (文章表)

🔑 id (UUID) PK

🔗 author_id FK → users

🔗 category_id FK → categories

title

content

status

📂 categories (分类表)

🔑 id (UUID) PK

name

slug

description

📊 resume_downloads

🔑 id (UUID) PK

downloaded_at

ip_address

user_agent

session_id

💬 comments (评论表)

🔑 id (UUID) PK

🔗 article_id FK

🔗 user_id FK

content

🏷️ tags (标签表)

🔑 id (UUID) PK

name

slug

设计特点与最佳实践

UUID 主键

分布式友好、不暴露数据量、合并数据无冲突

时间戳

所有表都有 created_at 和 updated_at

软删除

使用 status 字段而非物理删除，数据可恢复

3.5

API 接口设计

程序之间的"沟通语言"，就像餐厅的菜单。

GET

POST

PUT

PATCH

DELETE

RESTful 风格设计

🏥 健康检查

GET/api/v1/health→ 获取服务健康状态

📄 简历模块

POST/api/resume/download→ 记录下载事件

GET/api/resume/download-count→ 获取下载次数

📝 文章模块 (规划中)

GET/api/v1/articles→ 获取文章列表

POST/api/v1/articles→ 创建文章

响应格式规范

// ✅ 成功响应

{

"success": true,

"data": { ... },

"message": "获取成功"

}

// ❌ 错误响应

{

"success": false,

"error": { ... }

}

CHAPTER 04

前端架构
设计

FRONTEND ARCHITECTURE

4.1

什么是前端？

前端是用户直接看到和操作的部分——网页的界面。

布局和样式

好不好看

交互元素

好不好用

数据展示

内容是否正确显示

4.2

为什么选择 Nuxt.js？

SEO 友好

支持SSR，搜索引擎可以抓取页面内容

首屏加载快

服务端返回渲染好的HTML，无需等待JS

开发效率高

文件系统路由、自动导入、内置状态管理

TypeScript

原生支持，类型安全，减少运行时错误

部署灵活

支持 SSR、SSG、SPA 多种模式

4.3

前端项目结构

📁 frontend/

│

├── 📄 nuxt.config.ts # Nuxt 配置文件

├── 📄 package.json # 项目依赖清单

├── 📄 tailwind.config.js # Tailwind CSS 配置

│

├── 📁 app/

│ ├── 📁 assets/ # 静态资源

│ │ └── css/main.css

│ │

│ ├── 📁 components/ # Vue 组件

│ │ ├── Header.vue

│ │ └── Footer.vue

│ │

│ ├── 📁 layouts/ # 页面布局模板

│ │ └── default.vue

│ │

│ ├── 📁 pages/ # 页面文件（自动路由）

│ │ ├── index.vue → /

│ │ ├── about.vue → /about

│ │ └── articles/[id].vue → /articles/:id

│ │

│ └── 📁 composables/ # 组合式函数

│ └── useApi.ts

│

├── 📁 public/ # 公共静态文件

└── 📁 plugins/ # Nuxt 插件

4.4

核心概念解析

4.4.1 服务端渲染 (SSR) vs 客户端渲染 (CSR)

📱

客户端渲染 (CSR)

传统 SPA 方式

用户请求 → 服务器返回空白 HTML + JS

浏览器下载并执行 JS

JS 调用 API 获取数据

JS 渲染页面内容

用户终于看到内容 ⏱️ 较慢

缺点：首屏加载慢、SEO 不友好

本项目采用

🖥️

服务端渲染 (SSR)

Nuxt.js 默认模式

用户请求 → 服务器执行 JS，获取数据

服务器返回已渲染好的完整 HTML

用户立即看到内容 ⚡ 很快！

浏览器后台加载 JS，实现交互

优点：首屏加载快、SEO 友好

4.4.2 Tailwind CSS 原子化样式

// 传统 CSS 方式

<style>
  .card {
    background: white;
    padding: 16px;
    border-radius: 8px;
  }
</style>
<div class="card">内容</div>

// Tailwind CSS 方式（本项目采用）

<div class="bg-white p-4 rounded-lg shadow">
  内容
</div>
/*
  bg-white = 白色背景
  p-4 = padding 16px
  rounded-lg = 圆角
  shadow = 阴影
*/

无需切换文件直接在 HTML 中写样式

类名有规律容易记忆，开发速度快

自动优化生产构建时移除未使用的样式

4.5

前端配置详解

nuxt.config.ts// 核心配置解读

export default defineNuxtConfig({
  // 开发工具配置
  devtools: { enabled: true },
  // 使用的模块
  modules: [
    "@nuxtjs/tailwindcss", // Tailwind CSS 支持
    "nuxt-gtag", // Google Analytics 支持
  ],
  // Google Analytics 配置
  gtag: { id: "G-XDX0GQ2TKS" },
  // 应用元信息（SEO 相关）
  app: {
    head: {
      title: "凝神 - 个人作品集",
      meta: [
        { name: "description", content: "..." },
      ],
    },
  },
  // Nitro 服务器配置（API 代理）
  nitro: {
    devProxy: {
      "/api": { target: "http://localhost:8000" },
    },
  },
});

4.6

前端与后端的通信

🎨

前端

用户点击"下载简历"

调用 fetch('/api/resume/download')

显示"下载成功"提示

HTTP POST

→

←

JSON 响应

⚙️

后端

接收请求

记录下载信息

保存到数据库

返回成功响应

CHAPTER 05

运维与部署
架构

DEVOPS & DEPLOYMENT

5.1

什么是 DevOps？

Development（开发）+ Operations（运维） = 全流程自动化。

💻编码本地开发

📤提交GitHub

🏗️构建Docker

✅测试质量验证

🚀部署蓝绿部署

📊监控Prometheus

◀──────── 自动化 CI/CD 流水线 ────────▶

5.2

Docker 容器化架构

就像"集装箱"系统，保证环境一致性。

DOCKER NETWORK

🔀 Nginx (反向代理)

对外暴露 80/443

🎨 Frontend (Nuxt)

:3000 / Blue:3001 / Green:3002

⚙️ Backend (FastAPI)

:8000 / Blue:8001 / Green:8002

💾 PostgreSQL

Volume: postgres_data

⚡ Redis

Volume: redis_data

📊 Prometheus

:9090 (独立部署)

📈 Grafana

:3001

5.3

蓝绿部署详解

零停机部署，像换房子一样切换版本。

Phase 1

初始状态 - Blue 环境在线

用户流量

🔵 Blue 环境 (在线)

frontend-blue :3001
backend-blue :8001

🟢 Green 环境 (闲置)

等待部署...

Final Phase

流量切换 - Green 环境上线

用户流量

🟢 Green 环境 (新版本)

frontend-green :3002
backend-green :8002

🔵 Blue 环境 (待命/回滚)

保留，随时回滚

⏱️ 切换过程 < 10秒，用户无感知

5.4

CI/CD 流水线

GitHub Actions 自动化工作流。

JOB 1: LINT & TEST

Frontendpnpm lint, pnpm typecheck

Backendflake8, black --check

JOB 2: BUILD & PUSH

1. 登录阿里云 ACR

2. docker build -t ningshen-backend:latest .

3. docker push registry.../backend:latest

JOB 3: DEPLOY

1. SSH 连接服务器

2. ./deploy-blue-green.sh

3. curl health check

✅ 部署成功

5.5

服务器资源规划

2GB 内存限制下的精细分配。

PG 20%

BE 15%

FE 12%

R 7%

Nx 5%

System Reserved

0 MBTotal: 2048 MB

服务

内存限制

CPU 限制

备注

PostgreSQL

400 MB

0.5 核

shared_buffers=256MB

Backend

300 MB

0.5 核

FastAPI + Uvicorn

Frontend

250 MB

0.3 核

Nuxt SSR

Redis

150 MB

0.2 核

LRU 淘汰

💡 为什么要预留系统内存？

操作系统运行、文件系统缓存、突发流量缓冲、避免 OOM。

CHAPTER 06

安全架构
设计

SECURITY ARCHITECTURE

6.1

为什么安全很重要？

网站安全就像家庭安防——你不会把家门敞开着，同样网站也需要各种"锁"来保护数据和用户。

6.2

安全防护体系

🔒

传输层安全 (HTTPS)

SSL/TLS

所有数据传输加密，防止窃听。

Let's Encrypt

免费、自动续期。Certbot 每 12 小时检查，到期前 30 天续期。

Protocol

仅 TLSv1.2 / TLSv1.3。
HTTP 强制跳转 HTTPS。

🛡️

HTTP 安全头

Strict-Transport-Security

强制 HTTPS，防止降级攻击。

X-Frame-Options: DENY

禁止 iframe 嵌入，防止点击劫持。

X-Content-Type-Options: nosniff

禁止 MIME 类型猜测。

X-XSS-Protection: 1; mode=block

启用浏览器 XSS 过滤器。

🌐

跨域资源共享 (CORS)

配置"哪些域名可以访问我的 API"。

Allow Originsningshen.top, localhost

Allow MethodsGET, POST, PUT, DELETE

CredentialsTrue

🔐

密钥与敏感信息管理

❌ 不安全

硬编码在代码里

✅ 本项目

.env 环境变量

•.env 文件不提交到 Git (.gitignore)
•Docker Compose 自动注入
•生产环境独立配置

.env
# 数据库连接
DATABASE_URL=postgresql://user:pass@db:5432/ningshen
# 缓存
REDIS_URL=redis://:password@redis:6379/0
# 密钥
SECRET_KEY=your-super-secret-key-here

🐳

容器安全

User

非 root 用户运行
限制攻击者权限

Image

Alpine 最小化镜像
减少攻击面

Ports

仅暴露 Nginx 80/443
内部服务不对外

CHAPTER 07

监控与
可观测性

MONITORING & OBSERVABILITY

7.1

什么是可观测性？

可观测性就像汽车的仪表盘，让你随时知道系统状态。

车速

请求量

油量

资源使用率

温度

服务健康状态

故障灯

错误和告警

⚠️ 当前状态：

监控系统已完成配置，但考虑到服务器仅 2GB 内存，监控组件需额外 500MB，因此设计为独立部署、按需启用。

7.2

监控体系架构

Layer 01

数据采集层

Node Exporter

• CPU 使用率
• 内存使用
• 磁盘 I/O

cAdvisor

• 容器 CPU
• 容器内存
• 网络流量

应用埋点

• 请求延迟
• 错误率
• 业务指标

Layer 02

数据存储层

Prometheus

时序数据库 · PromQL 查询 · 保留 15 天

Layer 03

可视化层

📊 GRAFANA DASHBOARD

23%

CPU

65%

内存

150/s

请求

▃▅▇█▅▃

Layer 04

告警层 (规划中)

告警规则

• CPU > 80% 持续5分钟
• 错误率 > 1%
• 健康检查失败

通知渠道

• 邮件
• 钉钉/企业微信
• Slack

7.3

健康检查机制

定期询问服务"你还好吗？"

检查对象

检查地址

检查内容

Nginx

/health

返回 200 即健康

Backend

/api/v1/health

{"status": "healthy"}

PostgreSQL

pg_isready

数据库可接受连接

Redis

redis-cli ping

返回 PONG

# Docker Compose 配置
healthcheck:
  test: ["CMD", "curl", ...]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

7.4

日志管理

日志的作用

•

排查问题出了 bug 看日志找原因

•

审计追踪谁在什么时间做了什么操作

•

性能分析哪些请求慢，慢在哪里

🔮 未来改进：可接入 ELK Stack 或 Loki 实现集中式日志管理

// 结构化日志示例
{
"timestamp": "2026-02-11T10:30:45.123Z",
"level": "INFO",
"message": "Request completed",
"method": "GET",
"path": "/api/v1/health",
"status_code": 200,
"duration_ms": 12
}

Docker 日志配置

max-size: "10m"

max-file: "3"

每个容器最多 30MB 日志空间

FINAL CHAPTER

架构评估
与总结

EVALUATION & SUMMARY

8.1

架构评分

Overall Score8.1优秀的个人全栈项目

自动化程度9.0

部署能力9.0

可维护性8.5

文档完整度8.5

代码质量7.5

安全性7.5

可扩展性7.0

8.2

核心优点

🏗️

架构设计

• Monorepo 统一管理，版本一致性好
• 前后端分离，职责清晰
• 模块化设计，易于理解维护

🚀

部署能力

• 蓝绿部署，零停机更新
• 一键回滚，10秒内恢复
• CI/CD 全自动化

📊

运维友好

• 监控体系完善（按需启用）
• 结构化日志，排查有据
• 中文注释，门槛低

💰

成本优化

• 2GB 内存精细规划
• Alpine 镜像，存储成本低
• Let's Encrypt 零证书费

8.3

待改进点与演进方向

Priority High

自动化测试

当前：仅有代码风格检查

建议：添加单元测试、集成测试

数据库备份

当前：无自动备份

建议：pg_dump 定时备份到 OSS

告警通知

当前：仅收集指标

建议：配置 Alertmanager

Priority Medium

密钥管理

当前：.env 文件存储

建议：HashiCorp Vault / Secrets Manager

日志聚合

当前：各容器独立日志

建议：接入 ELK 或 Loki

Priority Low (Long-term)

CDN 加速

接入 Cloudflare / 阿里云 CDN

数据库高可用

主从复制、读写分离

Kubernetes

迁移到 K8s 实现弹性伸缩

8.4

适用场景

场景

适用性

说明

个人作品集/博客

✅

非常适合：本项目主要用途

小型团队项目

✅

适合：1-5人团队，日访问量 < 10万

MVP 快速验证

✅

适合：快速上线验证想法

中型企业应用

⚠️

需改造：水平扩展、数据库高可用

大型高并发系统

❌

不适合：需微服务架构、专业运维团队

THE ENDPROJECT DOCUMENTATION COMPLETE

凝神全栈

NINGSHEN-FULLSTACK

不仅仅是网站

开发

测试

构建

部署

运维

技术栈

前端技术

Nuxt.js 4

Vue 3

TypeScript

Tailwind

后端技术

FastAPI

Python 3.10

SQLAlchemy

asyncpg

存储 & 基础设施

线上环境

系统架构总览

SYSTEM ARCHITECTURE

什么是系统架构？

本项目架构风格

为什么选择这种架构？

系统架构图

用户

核心职责

路由规则

🎨 前端服务

⚙️ 后端服务

💾 PostgreSQL

⚡ Redis

请求处理流程示例

后端架构设计

BACKEND ARCHITECTURE

什么是后端？

后端应用结构

分层架构解析

📡 路由层 (Routers)

⚙️ 业务逻辑层 (Services)

💾 数据访问层 (Models)

🗄️ 数据库 (PostgreSQL)

数据库设计

设计特点与最佳实践

API 接口设计

响应格式规范

前端架构设计

FRONTEND ARCHITECTURE

什么是前端？

为什么选择 Nuxt.js？

SEO 友好

首屏加载快

开发效率高

TypeScript

部署灵活

前端项目结构

核心概念解析

4.4.1 服务端渲染 (SSR) vs 客户端渲染 (CSR)

客户端渲染 (CSR)

服务端渲染 (SSR)

4.4.2 Tailwind CSS 原子化样式

前端配置详解

前端与后端的通信

前端

后端

运维与部署架构

DEVOPS & DEPLOYMENT

什么是 DevOps？

Docker 容器化架构

蓝绿部署详解

初始状态 - Blue 环境在线

流量切换 - Green 环境上线

CI/CD 流水线

服务器资源规划

安全架构设计

SECURITY ARCHITECTURE

为什么安全很重要？

安全防护体系

系统架构
总览

后端架构
设计

前端架构
设计

运维与部署
架构

安全架构
设计

监控与
可观测性

架构评估
与总结