2026-moving-helper/README.md

Moving Helper Scaffold

这是一个面向可信家庭内网环境的小型工具项目，目前阶段只完成了基础脚手架：

• FastAPI
• Jinja2
• SQLAlchemy
• SQLite
• pytest / FastAPI TestClient
• Docker / Docker Compose

当前还不是完整业务应用，现阶段重点是把运行方式、工程结构、配置和基础测试打稳，后续再继续补 CRUD、图片、搜索等能力。

项目结构

.
├── app
│   ├── __init__.py
│   ├── config.py
│   ├── db.py
│   ├── main.py
│   ├── models.py
│   ├── static
│   │   └── style.css
│   └── templates
│       ├── base.html
│       └── boxes.html
├── data
├── tests
│   ├── conftest.py
│   └── test_app.py
├── docker-compose.yml
├── Dockerfile
├── README.md
├── requirements.txt
└── .gitignore

当前已接好的基础能力

• FastAPI 应用入口：app/main.py
• Jinja2 模板渲染
• 静态文件挂载：/static
• / 自动重定向到 /boxes
• SQLite 数据库连接
• SQLAlchemy Base / Session
• 启动时自动建表
• 基础自动化测试

轻量配置

项目通过环境变量支持下面几个配置项：

• DATABASE_URL
• HOST
• PORT

默认值：

• DATABASE_URL=sqlite:///./data/app.db
• HOST=0.0.0.0
• PORT=10000

本地开发和 Docker 运行都可以直接使用这些默认值，也可以按需覆盖。

本地开发模式

推荐使用本地 Python venv 开发和调试。

1. 创建虚拟环境

python3 -m venv .venv
source .venv/bin/activate

2. 安装依赖

pip install -r requirements.txt

3. 启动开发服务器

uvicorn app.main:app --reload --host 0.0.0.0 --port 10000

访问：

http://localhost:10000

本地开发默认会使用：

./data/app.db

如果你想临时改端口或数据库路径，也可以这样运行：

PORT=10000 DATABASE_URL=sqlite:///./data/app.db uvicorn app.main:app --reload --host 0.0.0.0 --port 10000

Docker 部署模式

Docker / Compose 是这个项目面向长期运行环境的方式。

启动

docker compose up --build

访问：

http://localhost:10000

运行说明

• 默认暴露 10000 端口
• restart: unless-stopped，适合长期运行
• 容器内应用以用户 1000:1000 运行
• SQLite 数据文件保存在宿主机 ./data/app.db
• 容器重建不会丢失数据库数据

数据持久化与备份

docker-compose.yml 会将宿主机目录：

./data

挂载到容器内：

/app/data

因此数据库文件通常位于：

./data/app.db

备份时直接复制这个 SQLite 文件即可。

测试

这个项目已经接入了最基础的测试设施：

• pytest
• FastAPI TestClient

运行测试：

pytest

测试会使用独立的测试数据库文件，不会污染本地开发使用的 data/app.db。

当前测试覆盖：

• 应用可正常启动
• / 会重定向到 /boxes
• /boxes 可正常返回 200
• 测试数据库与真实开发数据库隔离

当前阶段未实现

这一轮仍然没有开始做完整业务功能，下面这些内容后续再补：

• Box / Item 完整 CRUD
• 图片上传与处理
• 搜索
• 登录 / 鉴权
• 复杂前端样式
• 前后端分离