191 lines
5.3 KiB
Markdown
191 lines
5.3 KiB
Markdown
# 瑞小美系统技术栈标准与字符标准
|
||
|
||
## 技术栈
|
||
|
||
### 后端
|
||
|
||
| 技术 | 版本/说明 |
|
||
| --- | --- |
|
||
| **语言** | 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`<br>轩辕镜像：`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 次重试 |
|
||
|
||
健康检查配置示例：
|
||
|
||
```yaml
|
||
healthcheck:
|
||
test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
|
||
interval: 30s
|
||
timeout: 10s
|
||
retries: 3
|
||
```
|
||
|
||
### 日志管理
|
||
|
||
| 规范 | 说明 |
|
||
| --- | --- |
|
||
| **日志格式** | 统一使用 JSON 格式，便于收集分析 |
|
||
| **日志轮转** | 必须配置日志轮转，避免磁盘撑满 |
|
||
| **日志驱动** | Docker 容器使用 `json-file` 驱动并限制大小 |
|
||
|
||
日志配置示例：
|
||
|
||
```yaml
|
||
logging:
|
||
driver: "json-file"
|
||
options:
|
||
max-size: "10m"
|
||
max-file: "3"
|
||
```
|
||
|
||
### 资源限制
|
||
|
||
| 规范 | 说明 |
|
||
| --- | --- |
|
||
| **内存限制** | 所有容器应设置内存上限，防止单个服务耗尽资源 |
|
||
| **CPU 限制** | 根据服务负载合理分配 CPU 配额 |
|
||
| **建议配置** | 前端容器 256M-512M，后端容器 512M-1G |
|
||
|
||
资源限制配置示例：
|
||
|
||
```yaml
|
||
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 缓存 |
|
||
|
||
网络配置示例：
|
||
|
||
```yaml
|
||
networks:
|
||
scrm_network:
|
||
driver: bridge
|
||
```
|
||
|
||
### 敏感信息管理
|
||
|
||
| 规范 | 说明 |
|
||
| --- | --- |
|
||
| **禁止硬编码** | 密码、密钥等敏感信息禁止硬编码到代码或镜像中 |
|
||
| **环境变量** | 使用环境变量传递配置，通过 `.env` 文件管理 |
|
||
| **文件权限** | `.env` 文件权限设置为 600，禁止提交到 Git |
|
||
| **生产环境** | 生产环境使用 Docker Secrets 管理敏感数据 |
|
||
|
||
环境变量配置示例：
|
||
|
||
```yaml
|
||
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) |
|