add start-local.sh

docs/development-setup.md

@@ -55,6 +55,43 @@ pip install -r requirements.txt
 pip install -r requirements-dev.in
 ```
 
+### 2.1 本地启动脚本
+
+不需要打开 IDE 时，可以直接使用仓库内的启动脚本。脚本会自动定位项目根目录和虚拟环境，并以模块方式启动后端，避免 `ModuleNotFoundError: No module named 'app'`。
+
+```bash
+# 默认启动后端开发服务，前台运行，按 Ctrl+C 停止
+./scripts/start-local.sh
+./scripts/start-local.sh backend
+
+# 如果已经安装前端发布包，可启动完整的前后端服务
+./scripts/start-local.sh service start
+
+# 管理完整服务
+./scripts/start-local.sh stop
+./scripts/start-local.sh restart
+./scripts/start-local.sh status
+./scripts/start-local.sh logs --follow
+```
+
+默认会使用 `DEBUG=true` 和 `DEV=true`，与 IDE 开发启动保持一致；如果不需要热重载，可以这样启动以降低资源占用：
+
+```bash
+DEV=false ./scripts/start-local.sh
+```
+
+脚本会优先使用 `CONFIG_DIR`，其次使用 `MOVIEPILOT_CONFIG_DIR`，再检测 `~/Documents/moviepilot`，最后回退到仓库内的 `config` 目录。需要使用其他配置目录时，可以这样运行：
+
+```bash
+MOVIEPILOT_CONFIG_DIR=/path/to/moviepilot-config ./scripts/start-local.sh
+```
+
+首次使用前如果脚本没有执行权限，运行：
+
+```bash
+chmod +x scripts/start-local.sh
+```
+
 ### 3. 修改主程序依赖
 
 新增或升级依赖时，先确认依赖属于哪个层级：

scripts/start-local.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -P "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+MOVIEPILOT_BIN="$PROJECT_ROOT/moviepilot"
+VENV_PYTHON="$PROJECT_ROOT/venv/bin/python"
+
+show_usage() {
+  cat <<'EOF'
+用法：
+  ./scripts/start-local.sh                         启动后端开发服务（前台运行）
+  ./scripts/start-local.sh backend                 启动后端开发服务（前台运行）
+  ./scripts/start-local.sh service start          启动后端和已安装的前端服务
+  ./scripts/start-local.sh service start --safe   以安全模式启动完整服务
+  ./scripts/start-local.sh stop|restart|status    管理后端和前端服务
+  ./scripts/start-local.sh logs [OPTIONS]          查看后端日志
+  ./scripts/start-local.sh help                   显示本帮助
+EOF
+}
+
+if [[ ! -x "$MOVIEPILOT_BIN" ]]; then
+  printf '未找到本地 CLI：%s\n' "$MOVIEPILOT_BIN" >&2
+  exit 1
+fi
+
+if [[ ! -x "$VENV_PYTHON" ]]; then
+  printf '未找到项目虚拟环境：%s\n请先执行：%s install deps\n' "$VENV_PYTHON" "$MOVIEPILOT_BIN" >&2
+  exit 1
+fi
+
+# 显式传入配置目录，避免被仓库中的临时 .moviepilot.env 覆盖。
+if [[ -z "${CONFIG_DIR:-}" ]]; then
+  if [[ -n "${MOVIEPILOT_CONFIG_DIR:-}" ]]; then
+    CONFIG_DIR="$MOVIEPILOT_CONFIG_DIR"
+  elif [[ -d "${HOME:-}/Documents/moviepilot" ]]; then
+    CONFIG_DIR="${HOME}/Documents/moviepilot"
+  else
+    CONFIG_DIR="$PROJECT_ROOT/config"
+  fi
+fi
+export CONFIG_DIR
+export PYTHONUNBUFFERED="${PYTHONUNBUFFERED:-1}"
+export DEBUG="${DEBUG:-true}"
+export DEV="${DEV:-true}"
+
+cd "$PROJECT_ROOT"
+
+if [[ "$#" -eq 0 ]]; then
+  set -- backend
+fi
+
+command_name="$1"
+shift
+
+case "$command_name" in
+  backend|start)
+    if [[ "$#" -gt 0 ]]; then
+      printf '后端模块启动不接受额外参数；完整服务请使用：%s service start [OPTIONS]\n' "$0" >&2
+      exit 2
+    fi
+    exec "$VENV_PYTHON" -m app.main
+    ;;
+  service)
+    if [[ "$#" -eq 0 ]]; then
+      set -- start
+    fi
+    exec "$MOVIEPILOT_BIN" "$@"
+    ;;
+  stop|restart|status|logs|doctor|config|version)
+    exec "$MOVIEPILOT_BIN" "$command_name" "$@"
+    ;;
+  help|--help|-h)
+    show_usage
+    ;;
+  *)
+    printf '未知命令：%s\n\n' "$command_name" >&2
+    show_usage >&2
+    exit 2
+    ;;
+esac