skelet/docs/03-tech-stack.md

技术栈（Tech Stack）

“用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 架构设计。

一、技术栈一览

维度	选型	状态	理由 / 说明
CMS / Web 框架	Wagtail + Django	已定	内容模型、后台、页面、SEO、搜索和后续扩展都适合目录评测站。
Python	Python 3.12	已定	Wagtail 当前支持 Python 3.12；部署环境更稳。
版本钉死	requirements.txt 按实际安装版本 pin	T-001 落实	初始化时安装 pip 当前稳定版 Wagtail，用 pip show wagtail 确认版本后写成 wagtail==X.Y.Z，并回写本表。
数据库	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 / pytest 待定	待定	T-001 初始化后以项目实际生成结构为准。
开发环境	WSL2 / Linux + bash	已定	仓库根目录 /mnt/d/opc_project/skelet；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 流量。

三、构建与运行命令

生产代码尚未初始化。完成 T-001 后必须把本节替换为真实命令。

目标命令形态：

用途	命令
创建虚拟环境	python3.12 -m venv .venv
安装依赖	.venv/bin/pip install -r requirements.txt
数据库迁移	.venv/bin/python manage.py migrate
创建管理员	.venv/bin/python manage.py createsuperuser
本地开发	.venv/bin/python manage.py runserver
测试	.venv/bin/python 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。

五、依赖纪律

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