# willow-battle-project

**Repository Path**: aylerh/willow-battle-project

## Basic Information

- **Project Name**: willow-battle-project
- **Description**: 游戏-柳絮大作战
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 柳絮大作战

一个基于 FastAPI + SQLite + 原生前端 Canvas 的轻量网页游戏项目。玩家通过发射蛛网捕获柳絮、升级装备并逐关推进；项目同时支持 Docker Compose 部署、数据持久化和基础玩家进度保存。

## 项目概述

本项目围绕“柳絮来袭”的小游戏场景实现了完整的单应用闭环：

- 前端负责实时渲染、交互与关卡逻辑。
- 后端负责玩家数据、升级、通关与跳关接口。
- SQLite 负责本地持久化，数据目录通过 Docker volume 映射到宿主机。
- Docker Compose 负责统一启动、端口暴露和运行环境管理。

当前已经实现的核心能力包括：

- 玩家登录/创建存档。
- 柳絮生成、追踪、碰撞、受击与捕获。
- 装备升级：蛛网长度、速度、捕获能力。
- 关卡目标、剩余目标、自动通关进入下一关。
- 已通关关卡跳转。
- 暂停、继续、退出到主菜单。
- 死亡后重试当前关卡。
- 数据持久化保存到宿主机目录。

## 解决的痛点

本项目重点解决了以下几个实际问题：

### 1. 游戏运行环境不统一

痛点：本地 Python 版本、依赖安装、运行命令容易不一致。

解决方式：

- 使用 Dockerfile 构建统一运行镜像。
- 使用 docker-compose.yml 管理端口、环境变量和数据卷。
- 通过 `.env` 统一控制 `INNER_PORT` 与 `OUTER_PORT`。

### 2. 游戏数据容易丢失

痛点：容器重建后，玩家数据和进度可能丢失。

解决方式：

- 将 SQLite 数据文件放在 `/app/data`。
- 通过 volume 挂载到宿主机目录：

```yaml
volumes:
	- "H:/docker-data/willow-battle-project/data:/app/data"
```

这样即使容器删除，数据库文件仍保留在宿主机中。

### 3. SQLite 并发和性能默认配置偏弱

痛点：SQLite 默认配置在 Web 场景下容易出现锁等待和吞吐不足。

解决方式：

- 启用 WAL 模式。
- 设置 `synchronous = NORMAL`。
- 配置 `busy_timeout`、`cache_size`、`mmap_size` 等参数。

这使得项目在单实例、多用户轻并发场景下更适合生产化运行。

### 4. 版本迭代后旧数据库结构不兼容

痛点：新增字段后，旧数据库不会自动补列，可能导致接口报错。

解决方式：

- 应用启动时执行轻量迁移检查。
- 如果 `players` 表缺少 `max_level_reached` 字段，则自动执行 `ALTER TABLE` 补齐。

### 5. 游戏体验断点较多

痛点：死亡后只能重开、无法暂停、已通关关卡不能快速回跳。

解决方式：

- 增加暂停 / 继续 / 退出主菜单。
- 增加死亡后重试当前关卡。
- 增加总关数、已通关关数和已解锁关卡跳转。

## 使用技术

### 后端

- FastAPI：提供 HTTP API 和静态资源入口。
- SQLAlchemy：定义玩家模型并访问 SQLite。
- Pydantic：请求数据校验。
- python-dotenv：读取 `.env` 环境变量。
- Uvicorn：运行 ASGI 服务。

### 数据层

- SQLite：轻量级本地数据库。
- WAL 模式：提升读写并发能力。

### 前端

- HTML / CSS / JavaScript。
- Canvas 2D：实现游戏渲染与动画。
- Fetch API：与后端接口交互。

### 部署与运维

- Docker：封装运行环境。
- Docker Compose：统一构建、启动、端口和卷挂载。
- 清华镜像源：加速 apt 与 pip 依赖安装。

## 项目结构

```text
.
├─ app/
│  ├─ main.py          # FastAPI 入口与业务接口
│  ├─ database.py      # SQLite 连接与 PRAGMA 优化
│  ├─ models.py        # 玩家数据模型
│  └─ static/          # 前端页面、样式与游戏脚本
├─ data/               # SQLite 数据目录
├─ docs/               # 需求、实现与优化记录
├─ docker-compose.yml  # 容器编排
├─ Dockerfile          # 镜像构建
├─ requirements.txt    # Python 依赖
└─ readme.md
```

## 运行方法

### 1. 准备环境

需要先安装：

- Docker
- Docker Compose

Windows PowerShell 下在项目根目录执行。

### 2. 检查 `.env`

项目依赖端口环境变量，建议配置为：

```env
INNER_PORT=8206
OUTER_PORT=8206
DATABASE_URL=sqlite:///./data/game.db
```

如果 `.env` 已存在，只需确认端口配置正确即可。

### 3. 启动项目

在项目根目录执行：

```powershell
docker compose up --build
```

首次启动会完成：

- Python 依赖安装
- 镜像构建
- 容器启动
- 数据目录初始化
- SQLite 表创建与必要字段迁移

### 4. 访问项目

启动成功后，在浏览器打开：

```text
http://localhost:8206
```

如果你修改了 `OUTER_PORT`，则按对应端口访问。

### 5. 停止项目

```powershell
docker compose down
```

说明：执行 `down` 只会停止并删除容器，不会删除宿主机 `H:/docker-data/willow-battle-project/data` 下的数据。

## 数据持久化说明

当前 volume 配置为：

```yaml
volumes:
	- "H:/docker-data/willow-battle-project/data:/app/data"
```

其中：

- 宿主机目录：`H:/docker-data/willow-battle-project/data`
- 容器内目录：`/app/data`

SQLite 数据库文件会保存在该目录下，因此玩家存档、关卡进度、升级信息可以跨容器保留。

## 依赖列表

当前 Python 依赖包括：

- fastapi
- uvicorn
- sqlalchemy
- databases[sqlite]
- python-dotenv
- aiofiles
- pydantic
- pydantic-settings
- jinja2

## 页面样式

### 主页

![1](./images/1.png)