From 2c7dfad2b69f9e0ff0a35151e161bd69f535998d Mon Sep 17 00:00:00 2001
From: Codex <codex@localhost>
Date: Thu, 18 Jun 2026 03:39:25 +0800
Subject: [PATCH] =?UTF-8?q?=E5=AE=8C=E5=96=84=E7=BB=B4=E6=8A=A4=E5=85=A5?=
 =?UTF-8?q?=E5=8F=A3=E5=B9=B6=E5=A4=84=E7=90=86=E8=AF=BE=E7=A8=8B=E5=B0=8F?=
 =?UTF-8?q?=E7=BB=93=E5=AE=A1=E6=A0=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 Makefile           | 40 ++++++++++++++++++++++++++++++++++++++++
 app/MAINTENANCE.md |  2 ++
 app/README.md      | 16 ++++++++++++++++
 3 files changed, 58 insertions(+)
 create mode 100644 Makefile

diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..88d0994
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,40 @@
+SHELL := /bin/bash
+
+APP_DIR := app
+APP_MAKE := $(MAKE) -C $(APP_DIR) --no-print-directory
+COMPOSE := docker compose -f $(APP_DIR)/docker-compose.yml
+
+.PHONY: check smoke data-hash build up ps health deploy logs install-gitea-backup compose-config
+
+check:
+	$(APP_MAKE) check
+
+smoke:
+	$(APP_MAKE) smoke
+
+data-hash:
+	$(APP_MAKE) data-hash
+
+build:
+	$(APP_MAKE) build
+
+up:
+	$(APP_MAKE) up
+
+ps:
+	$(APP_MAKE) ps
+
+health:
+	$(APP_MAKE) health
+
+deploy:
+	$(APP_MAKE) deploy
+
+logs:
+	$(APP_MAKE) logs
+
+install-gitea-backup:
+	$(APP_MAKE) install-gitea-backup
+
+compose-config:
+	$(COMPOSE) config
diff --git a/app/MAINTENANCE.md b/app/MAINTENANCE.md
index 429e204..6495598 100644
--- a/app/MAINTENANCE.md
+++ b/app/MAINTENANCE.md
@@ -2,6 +2,8 @@
 
 新时空教务管理系统长期维护时，目标是每次更新都能做到可检查、可部署、可回滚，并且不误改业务数据。
 
+以下命令默认在仓库根目录 `/root/新时空教务管理系统` 执行。根目录 `Makefile` 会转发到 `app/` 下的实际应用配置；不要在根目录直接运行裸 `docker compose`，需要直接调用时使用 `docker compose -f app/docker-compose.yml <命令>`。
+
 ## 日常更新流程
 
 1. 查看当前改动：
diff --git a/app/README.md b/app/README.md
index d1c097c..bc49045 100644
--- a/app/README.md
+++ b/app/README.md
@@ -15,6 +15,22 @@
 - `scripts/install_launch_agent.py`：安装 Mac 开机常驻同步任务。
 - `launchd/com.xsk.education-management.sync.plist.template`：LaunchAgent 模板。
 
+## 维护入口
+
+推荐在仓库根目录 `/root/新时空教务管理系统` 执行日常维护命令：
+
+```bash
+make check
+make smoke
+make deploy
+```
+
+根目录 `Makefile` 会自动转发到 `app/` 下的实际应用配置，避免在错误目录执行 `docker compose` 或 `make deploy`。需要直接运行 Docker Compose 时，使用：
+
+```bash
+docker compose -f app/docker-compose.yml <命令>
+```
+
 ## 后端结构
 
 - `app/main.py`：FastAPI 应用入口，只负责注册路由和全局异常处理。