186 lines
3.4 KiB
Markdown
186 lines
3.4 KiB
Markdown
|
# Moving Helper Scaffold
|
||
|
|
|
||
|
|
这是一个面向可信家庭内网环境的小型工具项目，目前阶段只完成了基础脚手架：
|
||
|
|
|
||
|
|
- FastAPI
|
||
|
|
- Jinja2
|
||
|
|
- SQLAlchemy
|
||
|
|
- SQLite
|
||
|
|
- pytest / FastAPI TestClient
|
||
|
|
- Docker / Docker Compose
|
||
|
|
|
||
|
|
当前还不是完整业务应用，现阶段重点是把运行方式、工程结构、配置和基础测试打稳，后续再继续补 CRUD、图片、搜索等能力。
|
||
|
|
|
||
|
|
## 项目结构
|
||
|
|
|
||
|
|
```text
|
||
|
|
.
|
||
|
|
├── 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. 创建虚拟环境
|
||
|
|
|
||
|
|
```bash
|
||
|
|
python3 -m venv .venv
|
||
|
|
source .venv/bin/activate
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. 安装依赖
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pip install -r requirements.txt
|
||
|
|
```
|
||
|
|
|
||
|
|
### 3. 启动开发服务器
|
||
|
|
|
||
|
|
```bash
|
||
|
|
uvicorn app.main:app --reload --host 0.0.0.0 --port 10000
|
||
|
|
```
|
||
|
|
|
||
|
|
访问：
|
||
|
|
|
||
|
|
```text
|
||
|
|
http://localhost:10000
|
||
|
|
```
|
||
|
|
|
||
|
|
本地开发默认会使用：
|
||
|
|
|
||
|
|
```text
|
||
|
|
./data/app.db
|
||
|
|
```
|
||
|
|
|
||
|
|
如果你想临时改端口或数据库路径，也可以这样运行：
|
||
|
|
|
||
|
|
```bash
|
||
|
|
PORT=10000 DATABASE_URL=sqlite:///./data/app.db uvicorn app.main:app --reload --host 0.0.0.0 --port 10000
|
||
|
|
```
|
||
|
|
|
||
|
|
## Docker 部署模式
|
||
|
|
|
||
|
|
Docker / Compose 是这个项目面向长期运行环境的方式。
|
||
|
|
|
||
|
|
### 启动
|
||
|
|
|
||
|
|
```bash
|
||
|
|
docker compose up --build
|
||
|
|
```
|
||
|
|
|
||
|
|
访问：
|
||
|
|
|
||
|
|
```text
|
||
|
|
http://localhost:10000
|
||
|
|
```
|
||
|
|
|
||
|
|
### 运行说明
|
||
|
|
|
||
|
|
- 默认暴露 `10000` 端口
|
||
|
|
- `restart: unless-stopped`，适合长期运行
|
||
|
|
- 容器内应用以用户 `1000:1000` 运行
|
||
|
|
- SQLite 数据文件保存在宿主机 `./data/app.db`
|
||
|
|
- 容器重建不会丢失数据库数据
|
||
|
|
|
||
|
|
### 数据持久化与备份
|
||
|
|
|
||
|
|
`docker-compose.yml` 会将宿主机目录：
|
||
|
|
|
||
|
|
```text
|
||
|
|
./data
|
||
|
|
```
|
||
|
|
|
||
|
|
挂载到容器内：
|
||
|
|
|
||
|
|
```text
|
||
|
|
/app/data
|
||
|
|
```
|
||
|
|
|
||
|
|
因此数据库文件通常位于：
|
||
|
|
|
||
|
|
```text
|
||
|
|
./data/app.db
|
||
|
|
```
|
||
|
|
|
||
|
|
备份时直接复制这个 SQLite 文件即可。
|
||
|
|
|
||
|
|
## 测试
|
||
|
|
|
||
|
|
这个项目已经接入了最基础的测试设施：
|
||
|
|
|
||
|
|
- `pytest`
|
||
|
|
- `FastAPI TestClient`
|
||
|
|
|
||
|
|
运行测试：
|
||
|
|
|
||
|
|
```bash
|
||
|
|
pytest
|
||
|
|
```
|
||
|
|
|
||
|
|
测试会使用独立的测试数据库文件，不会污染本地开发使用的 `data/app.db`。
|
||
|
|
|
||
|
|
当前测试覆盖：
|
||
|
|
|
||
|
|
- 应用可正常启动
|
||
|
|
- `/` 会重定向到 `/boxes`
|
||
|
|
- `/boxes` 可正常返回 `200`
|
||
|
|
- 测试数据库与真实开发数据库隔离
|
||
|
|
|
||
|
|
## 当前阶段未实现
|
||
|
|
|
||
|
|
这一轮仍然没有开始做完整业务功能，下面这些内容后续再补：
|
||
|
|
|
||
|
|
- Box / Item 完整 CRUD
|
||
|
|
- 图片上传与处理
|
||
|
|
- 搜索
|
||
|
|
- 登录 / 鉴权
|
||
|
|
- 复杂前端样式
|
||
|
|
- 前后端分离
|