# 技术栈（Tech Stack）

> “用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 [架构设计](04-architecture.md)。

## 一、技术栈一览

| 维度 | 选型 | 状态 | 理由 / 说明 |
| --- | --- | --- | --- |
| CMS / Web 框架 | Wagtail + Django | 已定 | 内容模型、后台、页面、SEO、搜索和后续扩展都适合目录评测站。 |
| Python | Python 3.12 | 已定 | Wagtail 当前支持 Python 3.12；部署环境更稳。 |
| 版本钉死 | `requirements.txt` 按实际安装版本 pin | 已落实 | Wagtail 7.4.2 / Django 6.0.6，已 pin 全部依赖版本。 |
| 数据库 | SQLite with JSON1 | 已定 | 开发和第一版上线成本低；MVP 写入少。 |
| 后续数据库 | PostgreSQL | 条件触发 | 出现用户写入、高并发、后台多人编辑、锁冲突或会员功能后迁移。 |
| 前端模板 | Django Templates / Wagtail Templates | 已定 | 第一版以内容站为主，避免引入前后端分离复杂度。 |
| UI 样式方案 | 普通 CSS，必要时少量组件化模板 | 已定 | 减少构建链路；后续可再引入 Tailwind。 |
| 搜索 | Wagtail / 数据库搜索 | 已定 | MVP 不上 Elasticsearch。 |
| 鉴权方式 | Wagtail Admin Session | 已定 | 第一版只有后台编辑账号。 |
| 媒体存储 | 本地 media 目录 | 已定 | 2 核 2G VPS 第一版足够；后续可迁移 S3/R2/OSS。 |
| 部署方式 | 单 VPS，Gunicorn + Nginx | 待实现 | 面向 2 核 2G VPS；先不引入 Docker 作为必需项。 |
| 测试 | Django test | 已定 | T-001 初始化后以各 app `tests.py` 为准。 |
| 开发环境 | MSYS2 / MinGW + bash（Win 实测）；WSL2 / Linux 为目标环境 | 已定 | `init.sh` 为标准入口，`init.ps1` 可选辅助。 |
| 访问统计 | Plausible / Umami 或等价轻量方案 | 待实现 | 上线前接入（任务 T-305）；自然搜索和外链点击是 M3/M4 商业验证的前置数据。 |

## 二、决策记录与演进

- 当前选择 **Wagtail**，因为项目核心是内容管理、分类、筛选、详情页和 SEO，不是复杂 SaaS 流程。
- 当前选择 **SQLite**，因为第一版以公开读为主，后台只有少数编辑者写入。
- 当前选择 **Python 3.12**，因为比追最新 Python 更稳，且兼容当前 Wagtail。
- 当前不引入 **前后端分离 React**，避免第一版增加 API、构建和部署复杂度。
- 当前不引入 **Elasticsearch**，避免在 2 核 2G VPS 上增加运维负担。
- 当前不引入 **会员/支付系统**，先积累可信内容和 SEO 流量。

## 三、构建与运行命令

已完成初始化，以下为真实可用命令：

| 用途 | 命令 |
| --- | --- |
| 创建虚拟环境 | `python3.12 -m venv .venv` |
| 安装依赖 | `.venv/bin/pip3.12.exe install -r requirements.txt` |
| 数据库迁移 | `.venv/bin/python3.12.exe manage.py migrate` |
| 创建管理员 | `.venv/bin/python3.12.exe manage.py createsuperuser` |
| 本地开发 | `.venv/bin/python3.12.exe manage.py runserver` |
| 测试 | `.venv/bin/python3.12.exe manage.py test` |

> 开发环境使用系统已安装的 **Python 3.12.12**（命令 `python3.12`），不依赖 `python3` 别名。

## 四、SQLite 上线纪律

- 上线前验证 SQLite 支持 JSON1。
- 上线前启用 WAL 模式。
- 每天备份 `db.sqlite3` 和 `media/`。
- Gunicorn worker 控制在 1-2 个。
- 不做高频写入功能。
- 出现 `database is locked`、用户提交、评论、收藏、会员、多人后台编辑时，优先迁移 PostgreSQL。

## 五、依赖纪律

- 新增第三方依赖前，先说明用途、替代方案和维护成本。
- 不确定的技术选型先更新本文，再进入代码。
- 不允许同一职责并存两套框架或两套状态管理方案。
- 不要为了前端效果提前引入复杂构建链路。