《原神》的每日委托属于典型的固定重复任务场景:每天四个固定任务,完成后领取原石和冒险经验。单人玩还好,一旦要同时管理多个账号或者一个小队成员的日常进度,问题就变成:每个账号的任务做没做、谁还没打卡、连续多少天没断、需不需要提醒补做。这些信息靠聊天记录和手动表格很难维护。这篇文章从技术角度做一个可落地的“每日委托托管管理后台”。这里说的托管只管理任务进度数据本身,不接触游戏账号,不做自动操作,也不涉及人工代跑服务。文章会带读者用 FastAPI + SQLAlchemy + APScheduler + SQLite 从零搭一套最小系统:登记玩家账号、配置每日任务模板、自动生成当天任务、打卡完成、统计连续天数、定时发送未完成提醒。学完后可以直接用于个人或小队的日常任务管理,也可以迁移到任意固定周期任务场景。
1. 先想清楚:这个系统托管什么,不碰什么
1.1 业务场景:多账号重复日常任务为什么需要系统
很多玩家并不是只有一个账号。家庭共享账号、朋友互助账号、内容创作者的工作号,都会带来同一个问题:每天要登录好几个账号,完成同样的每日委托、清体力、领取奖励。任务本身不复杂,难点在于状态容易混乱。
没有系统的时候,通常靠记忆或聊天记录确认“今天有没有做过”。这种方式的缺陷很明显:
- 账号多,容易漏一个。
- 不知道每个账号具体完成了哪些任务。
- 无法判断连续完成天数,自然容易断签。
- 出现漏做后,只能靠事后补做,但当日委托已经刷新。
一个任务管理后台能解决的就是状态和提醒问题。它不负责替你打游戏,也不读取游戏内数据,只负责记录“哪个账号、哪天、哪个任务、是否完成”。这个信息闭环一旦建立起来,漏做率会明显下降,因为所有未完成记录会在晚上通过消息推送提醒一遍。
1.2 系统边界:哪些功能可以做,哪些不要碰
实现之前,先明确系统边界,避免设计出违反游戏规则或账号安全要求的功能。这个边界的判断标准很简单:系统只处理人工确认后的任务状态数据,不替用户登录游戏,不模拟用户行为。
| 可以做 | 不要碰 |
|---|---|
| 登记玩家账号备注,如 UID、昵称、区服 | 保存游戏账号密码 |
| 配置每日委托等固定任务模板 | 自动登录游戏客户端 |
| 自动生成每日任务记录 | 模拟点击、键盘操作、自动化打任务 |
| 人工打卡“已完成” | 读取或篡改游戏运行数据 |
| 统计连续完成天数、完成率 | 批量注册或监控他人账号 |
| 定时发送未完成提醒 | 做代跑交易、接单派单系统 |
这样设计不是为了限制功能,而是让项目保持合规和可维护。保存账号密码意味着极高的泄露风险,自动操作游戏则可能违反游戏运营规则。技术上也许都能实现,但成本和风险都超出了“日常任务管理工具”的范畴。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 技术选型与项目结构
2.1 技术栈选择及理由
这个项目的数据量很小,并发量也很低,核心价值在任务调度和数据口径,因此选择了轻量、容易跑通、便于部署的整套方案。
| 组件 | 选择 | 理由 |
|---|---|---|
| Web 框架 | FastAPI | 异步支持好,自动生成接口文档,适合快速迭代 |
| ORM | SQLAlchemy 2.x | 数据模型清晰,便于迁移到 MySQL / PostgreSQL |
| 数据库 | SQLite | 单机部署零依赖,适合学习和个人小组使用 |
| 定时任务 | APScheduler | 内置 cron 能力,负责每日生成记录和晚间提醒 |
| 时间处理 | zoneinfo / datetime | 避免使用不明确的本地时间,统一时区口径 |
| 依赖管理 | requirements.txt | 最少依赖,方便部署到服务器 |
FastAPI 对新手比较友好,因为接口可以直接在 /docs 页面调试,不需要额外搭建调试工具。SQLAlchemy 负责隔离数据库差异,后期如果团队要换 MySQL,只需要改连接串和少量配置。
2.2 目录结构与依赖配置
项目目录规划如下:
text复制daily_task_manager/
├── main.py # FastAPI 入口,路由与调度器注册
├── models.py # SQLAlchemy 数据模型
├── scheduler.py # APScheduler 定时任务
├── notify.py # 提醒消息推送封装
├── requirements.txt
└── daily_task.db # 首次运行后自动生成
这里不把代码拆成复杂的 package,目的是让一套最小闭环可以在半小时内完整跑通。模块拆分过细,反而会让新手卡在 import 路径上。
requirements.txt 内容如下:
text复制fastapi==0.111.0
uvicorn[standard]==0.30.1
sqlalchemy==2.0.30
apscheduler==3.10.4
requests==2.32.3
pydantic==2.7.4
需要注意,不同版本的 FastAPI 和 Pydantic 对类型声明略有差异。这里选用 2.x 版本的 FastAPI 和 Pydantic,代码中使用 str | None 这类写法时不会报错。如果使用旧版本,可能需要改成 Optional[str]。
3. 数据模型设计:把任务状态变成可查的记录
3.1 四张表的职责与字段
整个系统的核心是数据模型。先把玩家、任务模板、每日记录、周期计划拆开,后面接口就稳定了。
models.py 中的模型定义如下:
python复制from datetime import datetime
from sqlalchemy import (
Boolean,
Column,
Date,
DateTime,
ForeignKey,
Integer,
String,
UniqueConstraint,
func,
)
from sqlalchemy.orm import declarative_base, relationship
Base = declarative_base()
class Player(Base):
"""玩家账号,这里只存备注信息,不存任何登录凭证。"""
__tablename__ = "player"
id = Column(Integer, primary_key=True, autoincrement=True)
name = Column(String(50), nullable=False, unique=True)
region = Column(String(20), nullable=True, comment="区服或账号备注")
remark = Column(String(200), nullable=True)
created_at = Column(DateTime, server_default=func.now())
records = relationship("DailyRecord", back_populates="player")
class TodoTemplate(Base):
"""每日任务模板,例如每日委托、清体力、区域探索等。"""
__tablename__ = "todo_template"
id = Column(Integer, primary_key=True, autoincrement=True)
name = Column(String(100), nullable=False)
description = Column(String(255), nullable=True)
default_duration_minutes = Column(Integer, default=15, comment="预计耗时")
is_active = Column(Boolean, default=True)
created_at = Column(DateTime, server_default=func.now())
class DailyRecord(Base):
"""某个玩家在某天对某个任务的完成状态。"""
__tablename__ = "daily_record"
__table_args__ = (
UniqueConstraint(
"player_id", "template_id", "todo_date", name="uq_player_template_date"
),
)
id = Column(Integer, primary_key=True, autoincrement=True)
player_id = Column(Integer, ForeignKey("player.id"), nullable=False)
template_id = Column(Integer, ForeignKey("todo_template.id"), nullable=False)
todo_date = Column(Date, nullable=False, comment="任务所属日期")
done = Column(Boolean, default=False, nullable=False)
finished_at = Column(DateTime, nullable=True, comment="实际打卡时间")
remark = Column(String(200), nullable=True)
player = relationship("Player", back_populates="records")
class PeriodPlan(Base):
"""周期计划,例如 30 天连续打卡目标,用于扩展统计。"""
__tablename__ = "period_plan"
id = Column(Integer, primary_key=True, autoincrement=True)
player_id = Column(Integer, ForeignKey("player.id"), nullable=False)
plan_name = Column(String(100), nullable=False)
start_date = Column(Date, nullable=False)
end_date = Column(Date, nullable=False)
target_days = Column(Integer, default=30)
字段设计的关键点有三个:
todo_date使用Date而不是DateTime,因为任务归属到“天”,而不是具体的某个时刻。finished_at使用DateTime,记录打卡发生的精确时间,方便后续排查看是哪天几点完成的。Player.name设置unique=True,避免手工录入时重复创建同一个人。
3.2 UNIQUE 约束和 upsert:防止重复打卡的关键
DailyRecord 上的联合唯一约束是整套系统最核心的保障:
python复制UniqueConstraint(
"player_id", "template_id", "todo_date", name="uq_player_template_date"
)
它的含义是:同一个玩家在同一天对同一个任务只能有一条记录。如果没有这个约束,定时任务重复执行时会生成多条记录,打卡接口也会出现数据混乱。
打卡时不能盲目使用 INSERT,而应该先查询再决定是否更新。这种操作通常称为 upsert。后续接口实现里会用到这个逻辑。
注意:唯一约束是数据库层面的最后防线。应用层可以做校验,但不能完全依赖应用层解决并发写重复的问题。
4. 用 FastAPI 串通核心流程
4.1 应用初始化与通用依赖
主入口 main.py 负责创建数据库、注册路由、启动调度器。基础代码如下:
python复制from datetime import date, datetime, timedelta
from fastapi import Depends, FastAPI, HTTPException
from pydantic import BaseModel, Field
from sqlalchemy import create_engine
from sqlalchemy.orm import Session, sessionmaker
from models import Base, DailyRecord, Player, TodoTemplate
DATABASE_URL = "sqlite:///./daily_task.db"
engine = create_engine(
DATABASE_URL,
connect_args={"check_same_thread": False},
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base.metadata.create_all(bind=engine)
app = FastAPI(title="每日委托托管管理后台")
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
SQLite 默认在跨线程访问时可能报错,所以连接参数中要加 check_same_thread=False。学习环境这样写够用,生产环境换成 MySQL 时去掉这个参数即可。
4.2 玩家与模板接口
登记玩家和创建任务模板是第一步。先用 Pydantic 定义请求体:
python复制class PlayerCreate(BaseModel):
name: str = Field(..., min_length=1, max_length=50)
region: str | None = None
remark: str | None = None
class TemplateCreate(BaseModel):
name: str = Field(..., min_length=1, max_length=100)
description: str | None = None
default_duration_minutes: int = Field(15, ge=1, le=240)
然后实现两个创建接口:
python复制@app.post("/players")
def create_player(data: PlayerCreate, db: Session = Depends(get_db)):
exists = db.query(Player).filter(Player.name == data.name).first()
if exists:
raise HTTPException(status_code=400, detail="玩家名称已存在")
player = Player(name=data.name, region=data.region, remark=data.remark)
db.add(player)
db.commit()
db.refresh(player)
return {"id": player.id, "name": player.name}
@app.post("/templates")
def create_template(data: TemplateCreate, db: Session = Depends(get_db)):
template = TodoTemplate(
name=data.name,
description=data.description,
default_duration_minutes=data.default_duration_minutes,
)
db.add(template)
db.commit()
db.refresh(template)
return {"id": template.id, "name": template.name}
创建接口都先做重复校验,因为后续所有任务记录都依赖这两个基础数据。名称重复会导致数据口径混乱,统计时无法区分两个同名玩家。
4.3 自动生成当日任务:调度器
每日任务记录不需要手工创建,用 APScheduler 每天凌晨自动生成。这部分逻辑写在 scheduler.py:
python复制from datetime import date
from sqlalchemy.orm import Session
from models import DailyRecord, Player, TodoTemplate
def generate_daily_records(db: Session):
today = date.today()
players = db.query(Player).all()
templates = db.query(TodoTemplate).filter(TodoTemplate.is_active.is_(True)).all()
created_count = 0
for player in players:
for template in templates:
exists = (
db.query(DailyRecord)
.filter(
DailyRecord.player_id == player.id,
DailyRecord.template_id == template.id,
DailyRecord.todo_date == today,
)
.first()
)
if exists:
continue
db.add(
DailyRecord(
player_id=player.id,
template_id=template.id,
todo_date=today,
done=False,
)
)
created_count += 1
db.commit()
return created_count
这里先查存在性再插入,是因为数据库唯一约束只保证插不进去,但定时任务如果被重复触发,会产生大量异常日志。先查后插可以让任务保持幂等。
在 main.py 中注册调度任务:
python复制from apscheduler.schedulers.background import BackgroundScheduler
from scheduler import generate_daily_records
scheduler = BackgroundScheduler(timezone="Asia/Shanghai")
def scheduled_generate():
db = SessionLocal()
try:
count = generate_daily_records(db)
print(f"已生成 {count} 条今日记录")
finally:
db.close()
scheduler.add_job(scheduled_generate, "cron", hour=0, minute=5)
scheduler.start()
调度器使用 Asia/Shanghai 时区,避免服务器默认 UTC 时间导致凌晨任务提前或延后执行。
4.4 打卡状态更新
打卡接口负责把某条记录从“未完成”改为“已完成”。实现时需要处理三种情况:记录不存在、已经完成、正常完成。
python复制@app.post("/records/check")
def check_record(
player_id: int,
template_id: int,
db: Session = Depends(get_db),
todo_date: date | None = None,
):
target_date = todo_date or date.today()
record = (
db.query(DailyRecord)
.filter(
DailyRecord.player_id == player_id,
DailyRecord.template_id == template_id,
DailyRecord.todo_date == target_date,
)
.first()
)
if not record:
raise HTTPException(status_code=404, detail="记录不存在,请先生成当日任务")
if record.done:
return {
"message": "already_done",
"record_id": record.id,
"finished_at": record.finished_at,
}
record.done = True
record.finished_at = datetime.now()
db.commit()
db.refresh(record)
return {
"message": "ok",
"record_id": record.id,
"finished_at": record.finished_at,
}
为什么不直接使用 INSERT ... ON CONFLICT DO UPDATE 的数据库原生语法?因为 SQLAlchemy 在不同数据库上的方言支持程度不同,先查后写在当前数据规模下简单清晰,也方便在接口里返回友好的错误信息。
4.5 连续天数统计
统计是后台的核心价值之一。只看当天完成情况远远不够,用户更关心的是“这个账号已经连续完成多少天了”。
python复制@app.get("/players/{player_id}/stats")
def player_stats(player_id: int, days: int = 30, db: Session = Depends(get_db)):
today = date.today()
start = today - timedelta(days=days - 1)
records = (
db.query(DailyRecord)
.filter(
DailyRecord.player_id == player_id,
DailyRecord.todo_date >= start,
)
.all()
)
total_by_day = {}
done_by_day = {}
for record in records:
d = record.todo_date
total_by_day[d] = total_by_day.get(d, 0) + 1
if record.done:
done_by_day[d] = done_by_day.get(d, 0) + 1
full_done_days = 0
current_streak = 0
for offset in range(days):
d = start + timedelta(days=offset)
if total_by_day.get(d, 0) > 0 and done_by_day.get(d, 0) >= total_by_day[d]:
full_done_days += 1
current_streak += 1
else:
current_streak = 0
return {
"player_id": player_id,
"start_date": start,
"today": today,
"full_done_days": full_done_days,
"current_streak": current_streak,
"total_templates_per_day": len(set(total_by_day.values())) if total_by_day else 0,
}
这个统计里有一个容易忽略的口径问题:什么是“完成”?这里定义为“该玩家当天所有已登记模板都标记为 done”,而不是“完成其中任意一个”。如果团队想改成“完成任意一个就算完成日”,只需要把判断条件从 >= 改成 > 0。
5. 启动、验证与提醒闭环
5.1 启动服务和接口验证
安装依赖后启动服务:
bash复制uvicorn main:app --host 0.0.0.0 --port 8000 --reload
启动成功后访问 http://127.0.0.1:8000/docs 能看到 Swagger 文档。为了快速验证完整流程,可以用 curl 命令依次操作。
创建玩家:
bash复制curl -X POST "http://127.0.0.1:8000/players" \
-H "Content-Type: application/json" \
-d '{"name": "A账号", "region": "官服"}'
创建任务模板:
bash复制curl -X POST "http://127.0.0.1:8000/templates" \
-H "Content-Type: application/json" \
-d '{"name": "每日委托", "default_duration_minutes": 15}'
打卡:
bash复制curl -X POST "http://127.0.0.1:8000/records/check?player_id=1&template_id=1"
如果当天记录还没有生成,接口会返回 404。此时需要手动触发一次生成逻辑,或者等待调度器执行。
5.2 预期结果核对表
| 操作 | 预期返回 | 数据库变化 |
|---|---|---|
| 创建玩家 | {"id": 1, "name": "A账号"} |
player 表新增一条记录 |
| 创建模板 | {"id": 1, "name": "每日委托"} |
todo_template 表新增一条记录 |
| 生成当日记录 | 打印生成数量 | daily_record 表新增记录,done=False |
| 第一次打卡 | {"message": "ok", ...} |
对应记录 done=True,finished_at 写入 |
| 第二次打卡 | {"message": "already_done", ...} |
记录不变 |
| 查看统计 | 返回完整天数与连续天数 | 无变化 |
建议在调度器生成记录后,进数据库核对一次:
bash复制sqlite3 daily_task.db "select player_id, template_id, todo_date, done from daily_record order by todo_date desc limit 10;"
5.3 未完成提醒:企业微信机器人推送
打卡完成不是终点,提醒补做才是减少漏做的关键。晚间 20:00 检查所有未完成任务,通过企业微信群机器人发送内容。
notify.py 负责消息推送:
python复制import os
import requests
WEBHOOK_URL = os.getenv("WEBHOOK_URL", "")
def send_webhook_text(content: str):
if not WEBHOOK_URL:
print("未配置 WEBHOOK_URL,跳过推送")
return
payload = {"msgtype": "text", "text": {"content": content}}
response = requests.post(WEBHOOK_URL, json=payload, timeout=5)
response.raise_for_status()
调度任务中查询未完成记录并组装消息:
python复制def send_unfinished_reminder(db: Session):
today = date.today()
records = (
db.query(DailyRecord)
.filter(
DailyRecord.todo_date == today,
DailyRecord.done.is_(False),
)
.all()
)
if not records:
return
lines = []
for record in records:
player = record.player
template = record.template
lines.append(f"{player.name} 还没完成:{template.name}")
send_webhook_text("\n".join(lines))
把这个函数注册到调度器:
python复制scheduler.add_job(send_unfinished_reminder, "cron", hour=20, minute=0)
企业微信机器人的 webhook 地址必须放到环境变量或配置文件中,不能写死在代码里。这个地址一旦泄露,外部用户就能向群内推送任意内容。
6. 常见问题与排查路径
6.1 当天没有任何任务记录
现象:数据库里 daily_record 表为空,接口打卡返回 404。
排查顺序:
- 确认调度器是否打印了“已生成”日志。
- 确认
player表和todo_template表是否有数据。 - 确认系统当前时间是否已经过了 00:05。
- 检查
BackgroundScheduler的timezone参数与服务器时区是否一致。
如果一直没生成,手动调用一次生成函数,看是否报错。很多情况是模板的 is_active 为 False,或者玩家表为空。
6.2 重复打卡和数据唯一性异常
现象:同一玩家同一任务同一天出现多条记录,或者插入时报 UNIQUE constraint failed。
原因通常是:定时任务重复执行且没有先查后插,或者两个客户端并发打卡。应急处理方式是清理 daily_record 中重复行,并确保代码里保留先查后插逻辑。
检查重复数据:
sql复制select player_id, template_id, todo_date, count(*)
from daily_record
group by player_id, template_id, todo_date
having count(*) > 1;
清理时要注意保留一条记录,推荐保留 id 最小的那条。
6.3 uvicorn 热重载导致调度任务重复执行
现象:启动时开启了 --reload,每次保存代码后调度函数执行次数翻倍。
原因:--reload 会让 uvicorn 以父子进程方式运行,代码变更时重新加载模块,scheduler.start() 在当前写法下会被重复调用。
排查方式:日志里出现多条重复的“已生成”提示。解决方式有两种:开发时把调度器注册和使用拆开,或者生产环境不要加 --reload 参数运行。也可以把调度器启动放到 FastAPI 的 lifespan 事件中,在应用生命周期内只启动一次。
6.4 时区导致“昨天/今天”判断错位
现象:用户在晚上打卡后,统计接口把记录算到“明天”或“昨天”。
原因:date.today() 依赖操作系统时区,而调度器配置了 Asia/Shanghai,两者可能不一致,尤其是服务器默认 UTC 时。
解决方式:统一使用 zoneinfo 获取当前日期:
python复制from zoneinfo import ZoneInfo
def get_today():
return datetime.now(ZoneInfo("Asia/Shanghai")).date()
不要在代码里散落多个 date.today(),最好封装成一个函数统一调用。
6.5 SQLite 被占用和并发写入异常
现象:服务启动后访问接口时偶尔报 database is locked。
原因:SQLite 同一时刻只允许一个写事务,当多个请求或定时任务同时写库时会出现锁等待超时。
适合学习环境,但生产环境建议切换到 MySQL 或 PostgreSQL。如果短期内仍要使用 SQLite,可以给 create_engine 增加连接池参数:
python复制engine = create_engine(
"sqlite:///./daily_task.db",
connect_args={"check_same_thread": False},
pool_size=5,
max_overflow=10,
)
这类调整能缓解问题,但不能完全消除 SQLite 的并发写瓶颈。
7. 最佳实践与扩展方向
7.1 从学习环境到生产环境的补齐清单
当前项目是一个最小可运行版本,进入真正常驻服务之前,建议按下面的清单逐项补齐。
- 配置外置化:数据库地址、webhook 地址、调度时间全部放入环境变量或
.env文件。 - 日志:将定时任务执行、打卡操作、推送失败记录到文件或日志系统,避免只在控制台 print。
- 定时任务幂等:调度函数即使重复执行,也不能产生重复数据。
- 鉴权:后台接口至少加一层 Token 校验,防止局域网内任意请求修改任务状态。
- 异常处理:推送失败时不能影响主流程,应捕获异常并记录日志。
- 数据库备份:SQLite 用文件复制或
sqlite3 .backup定期备份;MySQL 则需要定时逻辑备份。 - 部署方式:用 Docker 固定 Python 版本和依赖版本,减少环境差异。
- 时间戳口径:数据库统一使用 UTC 或固定时区,展示层再转换。
7.2 可以继续扩展的方向
这个系统的数据模型完全通用,不只是能用在一款游戏的每日委托上。可以扩展的方向包括:
- 支持多个周期计划,例如按周为周期的“每周深境螺旋”任务。
- 增加签到日历视图,用前端展示每个玩家的连续完成天数。
- 支持钉钉、飞书、Telegram 等多种提醒渠道。
- 增加历史报表导出,便于月末复盘完成情况。
- 把模板复制能力做出来,配置一次即可用于多个玩家。
提醒渠道扩展时,建议在 notify.py 里抽象统一的消息接口,不要让定时任务直接依赖某个渠道的 SDK。
7.3 合规边界:这类系统最容易踩的雷
开发这类任务管理工具时,最容易踩的雷是把“状态管理”扩展成“自动执行”。记住几个原则:
- 不要保存玩家游戏账号和密码。
- 不要模拟游戏客户端操作。
- 不要读取或修改游戏内存数据。
- 不要接入任何代跑订单、派单和支付流程。
做提醒类工具时也要注意频率。晚上定时推送可以,但不要高频轰炸,否则对用户是一种干扰。功能边界画清楚之后,这个系统才适合长期维护和扩展。
建议先按这篇文章的最小版本跑通,确认数据生成、打卡、统计、提醒四个环节都稳定,再逐步补充前端界面和报表能力。如果团队里有多个需要管理日常任务的成员,这个后台也可以扩展成小组共享的工作台,但扩展时一定要守住不碰账号、不做自动操作的边界。
