012-kaopeilian/docs/规划/瑞小美系统技术栈标准与字符标准.md

瑞小美系统技术栈标准与字符标准

技术栈

后端

技术	版本/说明
语言	Python 3.11
框架	FastAPI
ORM	SQLAlchemy
数据库	MySQL 8.0
认证	OAuth

前端

类别	首选技术	说明
语言	TypeScript	类型安全，提升代码质量
框架	Vue 3	统一前端框架
构建工具	Vite	快速开发体验
包管理器	pnpm	高效、节省空间
UI组件库	Element Plus / Ant Design Vue	企业级UI
CSS方案	Tailwind CSS	可与组件库共存
HTTP客户端	Axios	统一请求库
状态管理	Pinia	按需使用
代码规范	ESLint	必须配置

前端（特殊场景可选）

技术	适用场景
qiankun	微前端架构整合
Uni-app	小程序/跨平台开发
Turborepo	Monorepo管理
React/Next.js	仅用于遗留系统维护

基础设施

技术	说明
容器化	Docker + Docker Compose
反向代理	Nginx（独立 Docker 容器部署）
网络	Docker Bridge Network
SSL	Let's Encrypt (Certbot)，在主机申请后挂载到容器

---

部署规范

基本原则

规范	说明
容器化部署	所有服务必须部署在 Docker 容器中，不可在容器外部署
前后端分离	前后端必须分离部署在不同 Docker 容器中，互相独立、解耦
服务编排	必须使用 Docker Compose 管理多服务与依赖关系
统一入口	必须通过 Nginx 反向代理提供统一入口，后端不直接暴露公网
热重载	开发环境必须启用代码热重载（HMR/auto-reload）

Nginx 配置规范

规范	说明
独立部署	Nginx 部署在独立 Docker 容器中
路由转发	根据不同子域名转发到对应的 Docker 容器
SSL 终止	仅在 Nginx 层配置 SSL 证书
端口暴露	仅 Nginx 容器暴露 80/443 端口，其他服务端口绑定 127.0.0.1

镜像源配置

类型	首选镜像	备用镜像
Docker Registry	阿里云：https://kjphlxn2.mirror.aliyuncs.com	DaoCloud：https://docker.m.daocloud.io 轩辕镜像：https://docker.xuanyuan.me
APT 源	阿里云：http://mirrors.aliyun.com/debian/	-
通用镜像站	阿里云：https://developer.aliyun.com/mirror	-

镜像版本规范

规范	说明
禁用 latest	ACR 镜像加速器已停止同步 latest 标签
指定版本号	必须使用具体版本号，如 python:3.11.9-slim

健康检查

规范	说明
必须配置	所有服务容器必须配置健康检查
检查端点	后端服务应提供 /health 或 /api/health 端点
检查间隔	建议 30 秒检查一次
超时设置	建议 10 秒超时，3 次重试

健康检查配置示例：

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
  interval: 30s
  timeout: 10s
  retries: 3

日志管理

规范	说明
日志格式	统一使用 JSON 格式，便于收集分析
日志轮转	必须配置日志轮转，避免磁盘撑满
日志驱动	Docker 容器使用 json-file 驱动并限制大小

日志配置示例：

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

资源限制

规范	说明
内存限制	所有容器应设置内存上限，防止单个服务耗尽资源
CPU 限制	根据服务负载合理分配 CPU 配额
建议配置	前端容器 256M-512M，后端容器 512M-1G

资源限制配置示例：

deploy:
  resources:
    limits:
      cpus: '1'
      memory: 512M
    reservations:
      cpus: '0.25'
      memory: 128M

网络隔离

规范	说明
自定义网络	不同项目使用独立 Docker 网络，避免容器间意外通信
内部通信	容器间使用容器名通信，不使用硬编码 IP
网络命名	网络名称格式：项目名_network，如 scrm_network
DNS 刷新	后端容器重启后，需执行 docker exec nginx_proxy nginx -s reload 刷新 nginx DNS 缓存

网络配置示例：

networks:
  scrm_network:
    driver: bridge

敏感信息管理

规范	说明
禁止硬编码	密码、密钥等敏感信息禁止硬编码到代码或镜像中
环境变量	使用环境变量传递配置，通过 .env 文件管理
文件权限	.env 文件权限设置为 600，禁止提交到 Git
生产环境	生产环境使用 Docker Secrets 管理敏感数据

环境变量配置示例：

env_file:
  - .env
environment:
  - DATABASE_URL=${DATABASE_URL}
  - SECRET_KEY=${SECRET_KEY}

---

字符标准

项目	标准
字符编码	UTF-8
数据库字符集	utf8mb4 (支持 emoji 表情)
数据库排序规则	utf8mb4_unicode_ci
API 响应	JSON (UTF-8 编码)
日期格式	ISO 8601 (YYYY-MM-DDTHH:mm:ss)
时区	Asia/Shanghai (UTC+8)