敏捷编码
vs
传统编码

传统瀑布模型中，编码是翻译设计文档的执行阶段；
敏捷模型中，编码是持续探索与交付价值的创造阶段。

TRADITIONAL

设计文档 100% 完成

详细设计评审

编码（翻译文档）

单元测试

集成测试（后期）

上线（数月后）

AGILE / 本项目

用户故事驱动

编码 + 测试（同步进行）

CI 自动验证

CD 自动部署

监控反馈 → 下一迭代

持续循环，每日可部署

反馈周期

分钟~小时

数周~数月

部署频率

每日

季度/年

变更成本

低

高

700

1.2

编码
里程碑

700

次提交

🚀

项目初始化

#1-#30

项目结构搭建、基础配置

Commit

Initial commit、add .gitignore

🔧

CI/CD 搭建

#31-#150

GitHub Actions、镜像构建、部署脚本

Commit

ci: 在 docker-compose.yml 中添加 GitHub Actions 配置

🎨

前端开发

#151-#400

页面组件、路由、样式系统

Commit

feat: 凝神将 HTML 组件化为 Vue 组件

⚙️

后端开发

#401-#500

API 路由、数据库模型、中间件

Commit

feat: 配置 SSL 证书和自动部署

📝

文档完善

#501-#600

README、开发规范、架构文档

Commit

docs: 项目创建总结与架构说明

🔄

持续优化

#601-#700

性能优化、Bug 修复、功能迭代

Commit

refactor: 将页面拆分为可复用组件

01 / Architecture Overview

Tech Stack

四层架构设计，从前端到基础设施的完整技术选型方案

Frontend

NuxtVueTSTailwind

Backend

FastAPIPythonSQLAlchemyPydantic

Data

PostgreSQLRedis

Infra

DockerNginxCI/CDACR

Layers

Core Techs

SSR

Mode

Section 02

技术栈详情

四层架构设计，覆盖前端到基础设施

Nuxt.js 4

全栈框架

响应式UI

TypeScript

类型安全

Tailwind

原子CSS

Tools

pnpm + ViteESLintvue-tsc

FastAPI

异步框架

Python 3.10

运行时

SQLAlchemy

ORM框架

Pydantic

数据验证

Tools

Uvicornflake8black

PostgreSQL

关系型数据库

Redis 7

缓存存储

Tools

ACID事务LRU淘汰会话管理

Docker

容器化

Nginx

反向代理

GitHub Actions

CI/CD

阿

阿里云ACR

镜像仓库

Tools

BuildKit多阶段构建

Section 03

编码规范体系

Format

# Commit Message

# Example

feat(resume): 添加下载统计

Types

feat新功能

fixBug 修复

docs文档更新

refactor代码重构

02 / Project Architecture

Code
Structure

全栈项目结构设计
清晰的分层架构与模块化组织

50+

Components

API Routes

Docker Services

Section 01

整体目录结构

点击目录或文件查看详细说明

Frontend

Backend

Infrastructure

Configuration

ningshen-fullstack/

+.github/GitHub 配置

−frontend/前端应用

+app/

+public/静态资源

+server/服务端配置

−nuxt.config.tsNuxt 配置

−tailwind.config.jsTailwind 配置

−Dockerfile镜像构建

+backend/后端应用

+database/数据库初始化

+nginx/Nginx 配置

+scripts/脚本工具

+docs/项目文档

−docker-compose.yml开发环境编排

−docker-compose.blue-green.yml生产蓝绿部署

−README.md项目说明

Section 02

前端组件架构

50+ Vue 组件，按功能模块组织

命名规范

Base*.vue基础通用组件

The*.vue单例组件

*Section.vue页面区块组件

*Card.vue卡片类组件

首页组件

8 files

WelcomeSection.vue

欢迎页

ManifestoSection.vue

个人宣言

CoreSkillsSection.vue

核心技能

ExperienceSection.vue

工作经历

BucketTheorySection.vue

木桶理论

TShapedSection.vue

T型人才

ResumeSection.vue

简历下载

ContactMapSection.vue

联系方式

导航组件

2 files

MainNavigation.vue

主导航栏

FooterNavigation.vue

页脚导航

基础 UI 组件

3 files

BaseButton.vue

按钮

BaseInput.vue

输入框

BaseModal.vue

模态框

功能模块

3 files

ningshen/

凝神产品

lab/

实验室

notes/

笔记模块

Section 03

后端模块架构

三层架构设计：路由层、模型层、配置层

Routers

路由层

API 端点定义，处理 HTTP 请求

health.pyresume.py(规划中) users.py

Models

模型层

数据模型定义，ORM 映射

resume.pyuser.py (规划)

Config

配置层

应用配置管理，环境变量加载

config.pydatabase.py

03 / DevOps Pipeline

CI/CD
Pipeline

自动化构建、测试、部署流水线
从代码提交到生产环境的全流程自动化

Pipeline Active

3-5 min build time

01Lint & Test1-2 min

02Build & Push2-3 min

03Deploy1 min

Trigger:push → main / develop

Section 01

自动化流水线

GitHub Actions 工作流
三阶段自动化流水线

Job 1

lint-and-test

1-2 min

代码质量检查

○pnpm install

○pnpm lint (ESLint)

○pip install -r requirements-dev.txt

○flake8 app/

○black --check app/

Job 2

build-and-push

2-3 min

构建并推送镜像

○docker pull → ACR/postgres

○docker pull → ACR/redis

○docker pull → ACR/nginx

○docker build frontend

○docker build backend

○docker push to ACR

Job 3

deploy

1 min

自动部署

○rsync 同步代码

○tar 打包上传

○SSH 执行部署脚本

○curl 健康检查

○Nginx 流量切换

Section 02

代码质量门禁

自动化代码检查，确保代码质量
检查失败将阻止合并

Check

Tool

Rule

Status

1前端代码规范

ESLint

@nuxt/eslint 规则集

2TypeScript 类型

vue-tsc

严格模式

3Python 代码风格

flake8

max-line-length=100

4Python 代码格式

black

默认配置

Passed

Warning

Section 03

核心配置

GitHub Actions 工作流配置片段

.github/workflows/ci-cd-improved.yml

lint-and-test:
  runs-on: ubuntu-latest
  steps:
    - name: 前端依赖安装与代码检查
      run: |
        cd frontend
        pnpm install
        pnpm lint          # ESLint 规范检查
    - name: 后端代码检查
      run: |
        cd backend
        pip install -r requirements-dev.txt
        python -m flake8 app/ --max-line-length=100
        python -m black --check app/

Configuration Notes

01pnpm install 安装前端依赖

02ESLint 执行代码规范检查

03flake8 检查 Python 风格

04black 验证代码格式

Environment A

Blue

当前运行中

Environment B

Green

待部署环境

02/Blue-Green Deployment

Blue 环境

Green 环境

切换

Section 01

部署架构

Layer 01

🌐 用户请求

Layer 02

Nginx 反向代理

upstream 动态切换

Blue 环境

frontend-blue

backend-blue

当前活跃

Green 环境

frontend-green

backend-green

待切换

Layer 03

共享数据层

PostgreSQL

Redis

← 不参与蓝绿切换 →

Section 02

部署流程

6 步完成零停机部署

拉取最新镜像

从 ACR 拉取最新的 frontend 和 backend 镜像

docker pull ACR/ningshen-backend:latest

启动 Green 环境

启动新版本容器，Blue 继续处理流量

docker compose up -d backend-green frontend-green

健康检查

30 次重试，间隔 2 秒

curl -sf http://backend-green:8000/health

✓

继续

✗

回滚到 Blue

切换 Nginx upstream

更新配置并重载 Nginx

nginx -s reload

保存部署状态

记录当前活跃环境

echo "green" > .deployment-state

停止旧环境

Blue 作为备份暂不删除，支持快速回滚

docker compose stop backend-blue frontend-blue

部署时间

1-2 分钟

用户感知

零停机

05 / Development Environment

Local
Setup

快速搭建本地开发环境
两种启动方式灵活切换

Available Services

Frontend

:3000

Backend

:8000

PostgreSQL

:5432

Redis

:6379

Quick Start:docker-compose up -d

Section 01

启动方式

两种开发环境启动方式
根据需求灵活选择

development-mode

Step 1启动数据库服务

$docker-compose up -d postgres rediscopy

Step 2启动后端

$cd backendcopy

$python -m venv .venvcopy

$source .venv/bin/activatecopy

$pip install -r requirements.txtcopy

$uvicorn app.main:app --reload --host 0.0.0.0 --port 8000copy

Step 3启动前端（新终端）

$cd frontendcopy

$pnpm installcopy

$pnpm devcopy

Tip

分别启动适合开发调试，支持热重载和断点调试

Section 02

启动步骤

分步启动的详细说明

启动数据库

启动 PostgreSQL 和 Redis 容器

docker-compose up -d

postgres:5432

redis:6379

启动后端

Python 虚拟环境与 FastAPI 服务

python -m venv

pip install

uvicorn --reload

启动前端

Nuxt.js 开发服务器

pnpm install

pnpm dev

localhost:3000

Section 03

端口分配

开发与生产环境端口规划

Service

Dev Port

Prod Port

Description

Frontend

:3000

:3001/3002

Nuxt.js SSR

Backend

:8000

:8001/8002

FastAPI

PostgreSQL

:5432

数据库

Redis

:6379

缓存

Nginx

:-

:80/443

反向代理

Frontend

Backend

Data

Proxy

— Chapter 06 / Project Assets

Core
Deliver
ables

项目核心产出物清单
代码、文档、运维资产一览

Code Assets

源码、配置、脚本

types

Doc Assets

文档与知识沉淀

docs

Ops Assets

部署与运维资产

assets

Total Assets

ningshen-fullstack

Project Name

All Active

Section 01

代码资产

项目核心代码产出
按类型分类管理

Type

Path

Description

前端源码

frontend/app/

50+ Vue 组件

后端源码

backend/app/

FastAPI 路由和模型

数据库迁移

backend/alembic/versions/

Schema 版本管理

CI/CD 配置

.github/workflows/

自动化流水线

部署脚本

scripts/deploy/

蓝绿部署实现

Docker 配置

docker-compose*.yml

容器编排

Frontend50+

Backend10+

Scripts5+

Section 02

文档资产

项目文档与知识沉淀

系统架构

整体架构设计文档

系统设计与架构.md

编码实现

编码阶段详细文档

本文档

开发规范

团队编码规范指南

docs/开发规范/README.md

敏捷实践

DevOps 方法论文档

docs/0 敏捷-DevOps模型/

Section 03

运维资产

部署与运维相关资产

ACR

阿里云 ACR 镜像

前端/后端/基础镜像仓库

Active

SEC

GitHub Actions Secrets

部署密钥与敏感配置

Active

SSL

Let's Encrypt 证书

自动续期 SSL 证书

Active

MON

监控配置

Prometheus + Grafana（可选）

Active

Infrastructure Overview

Docker Compose

Nginx

PostgreSQL

Redis

GitHub Actions

Aliyun ACR

Commits

Git Iterations

— Chapter 08 / Conclusion

Summary

700 次迭代的价值
敏捷 DevOps 编码实践的完整历程

Core Values

Philosophy

Section 01

核心价值

700 次迭代沉淀的价值理念

持续迭代

从 Initial commit 到完整产品，每一次提交都是一次改进

自动化驱动

CI/CD 流水线保障代码质量，每次提交分钟级反馈

零停机部署

蓝绿部署实现业务连续性，用户完全无感知

代码即文档

规范的代码结构、清晰的 Commit 历史自解释

快速反馈

问题早发现早解决，变更成本低

拥抱变化，
持续交付价值

与传统瀑布模型相比，敏捷编码不再是「翻译设计文档」的机械过程，
而是持续探索与学习的创造旅程。

Waterfall

翻译设计文档

机械执行过程

Agile

持续探索学习

创造价值旅程

Project Metrics

项目数据一览

700

Commits

Git Iterations

50+

Components

Vue Components

Layers

Architecture

<5min

Build Time

CI/CD Pipeline

敏捷编码vs传统编码

编码里程碑

Tech Stack

技术栈详情

编码规范体系

CodeStructure

整体目录结构

前端组件架构

首页组件

导航组件

基础 UI 组件

功能模块

后端模块架构

路由层

模型层

配置层

CI/CDPipeline

自动化流水线

lint-and-test

build-and-push

deploy

代码质量门禁

核心配置

部署架构

部署流程

LocalSetup

启动方式

启动步骤

启动数据库

启动后端

启动前端

端口分配

CoreDeliverables

Code Assets

Doc Assets

Ops Assets

代码资产

文档资产

系统架构

编码实现

开发规范

敏捷实践

运维资产

阿里云 ACR 镜像

GitHub Actions Secrets

Let's Encrypt 证书

监控配置

Summary

核心价值

持续迭代

自动化驱动

零停机部署

代码即文档

快速反馈

拥抱变化，持续交付价值

项目数据一览

敏捷编码
vs
传统编码

编码
里程碑

Code
Structure

CI/CD
Pipeline

Local
Setup

Core
Deliver
ables

拥抱变化，
持续交付价值