From 55b684fbe14169bccbea20788f72b4c4168cc24b Mon Sep 17 00:00:00 2001 From: Simon Date: Mon, 7 Sep 2026 20:13:39 +0800 Subject: [PATCH] =?UTF-8?q?feat(scripts):=20dev.sh=20=E5=89=8D=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=E4=B8=80=E9=94=AE=20start/stop/restart/status/logs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 启动后端 uvicorn(:8000, --reload, 0.0.0.0) + 前端 next dev(:3000)，setsid 独立进程组 - 停止按 pidfile + 监听端口双定位，整进程组清理（无子进程残留，实测残留 0） - 端口探测 ss 优先（lsof 在该环境对 socket 不可靠） - status/logs/restart；支持 API_PORT/WEB_PORT/BACKEND_API_URL 覆盖 - 日志落 logs/，pid 落 .run/（均已 gitignore）；USAGE §5 增加用法 --- .gitignore | 4 ++ docs/USAGE.md | 15 ++++ scripts/dev.sh | 184 +++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 203 insertions(+) create mode 100755 scripts/dev.sh diff --git a/.gitignore b/.gitignore index 447aa00..9651d1a 100644 --- a/.gitignore +++ b/.gitignore @@ -53,3 +53,7 @@ experiments/* # ================= archify 视觉验证副产物（重新生成即可） ================= docs/diagrams/*.visual-check.* + +# ================= 运行期（dev.sh 管理） ================= +.run/ +logs/ diff --git a/docs/USAGE.md b/docs/USAGE.md index 4e9ebad..3ba5b42 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -126,6 +126,21 @@ uv run python -m app.cli.sync export [--years 2023,2024] # 日线 ## 5. 启动 +**一键脚本（后端 + 前端同时管理）**： + +```bash +scripts/dev.sh start # 启动后端(8000) + 前端(3000) +scripts/dev.sh status # 查看状态 +scripts/dev.sh restart # 重启 +scripts/dev.sh stop # 停止 +scripts/dev.sh logs api # 跟踪后端日志（web 同理） + +# 局域网访问前端时（例如 http://192.168.1.160:3000）： +# BACKEND_API_URL=http://192.168.1.160:8000 scripts/dev.sh start +``` + +手动分别启动见下： + ```bash # 后端（端口 8000） cd backend diff --git a/scripts/dev.sh b/scripts/dev.sh new file mode 100755 index 0000000..3984a9c --- /dev/null +++ b/scripts/dev.sh @@ -0,0 +1,184 @@ +#!/usr/bin/env bash +# ============================================================ +# qlib-platform 前后端一键管理脚本 +# +# 用法： +# scripts/dev.sh start 启动后端(8000) + 前端(3000) +# scripts/dev.sh stop 停止两者 +# scripts/dev.sh restart 重启两者 +# scripts/dev.sh status 查看状态 +# scripts/dev.sh logs [api|web] 实时查看日志 +# +# 环境变量（可选）： +# API_PORT 后端端口（默认 8000） +# WEB_PORT 前端端口（默认 3000） +# BACKEND_API_URL 前端同源代理指向的后端地址（默认 http://127.0.0.1:8000， +# 局域网访问前端时改为 http://<本机IP>:8000） +# +# 进程管理说明：pidfile 记录启动进程；停止时同时按「监听端口」定位真实服务进程 +# （pnpm/uv 包装进程可能提前退出），并对整进程组停止，避免子进程残留。 +# ============================================================ +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" +RUN_DIR="$ROOT/.run" +LOG_DIR="$ROOT/logs" +mkdir -p "$RUN_DIR" "$LOG_DIR" + +API_PORT="${API_PORT:-8000}" +WEB_PORT="${WEB_PORT:-3000}" +BACKEND_API_URL="${BACKEND_API_URL:-http://127.0.0.1:8000}" + +API_PID_FILE="$RUN_DIR/backend.pid" +WEB_PID_FILE="$RUN_DIR/frontend.pid" +API_LOG="$LOG_DIR/backend.log" +WEB_LOG="$LOG_DIR/frontend.log" + +log() { echo "[dev.sh] $*"; } +die() { echo "[dev.sh] 错误: $*" >&2; exit 1; } + +# ---------- 进程探测 ---------- + +# 监听指定端口的 pid（无则空） +listener_pids() { # $1 port —— ss 优先（lsof 在部分环境对 socket 不可靠） + if command -v ss >/dev/null 2>&1; then + ss -tlnp 2>/dev/null | awk -v p=":$1 " ' + $0 ~ p && /LISTEN/ { + if (match($0, /pid=[0-9]+/)) print substr($0, RSTART+4, RLENGTH-4) + }' + elif command -v lsof >/dev/null 2>&1; then + lsof -t -iTCP:"$1" -sTCP:LISTEN 2>/dev/null || true + fi +} + +port_in_use() { [[ -n "$(listener_pids "$1")" ]]; } + +pidfile_alive() { [[ -f "$1" ]] && kill -0 "$(cat "$1")" 2>/dev/null; } + +# 杀掉指定 pid 及其整进程组（uvicorn --reload / next dev 的子进程一起清理） +kill_tree() { # $1 pid + local pid pgid + pid="$1" + pgid="$(ps -o pgid= -p "$pid" 2>/dev/null | tr -d ' ' || true)" + [[ -n "${pgid:-}" ]] && kill -- "-$pgid" 2>/dev/null || true + kill "$pid" 2>/dev/null || true + pkill -P "$pid" 2>/dev/null || true +} + +# ---------- 启动 ---------- + +start_api() { + if port_in_use "$API_PORT"; then + log "后端已在 :$API_PORT 运行（pid $(listener_pids "$API_PORT" | head -1)）" + listener_pids "$API_PORT" | head -1 > "$API_PID_FILE" + return 0 + fi + log "启动后端 :$API_PORT（日志 $API_LOG）" + ( cd "$ROOT/backend" + setsid nohup uv run uvicorn app.main:app --host 0.0.0.0 --port "$API_PORT" --reload \ + >>"$API_LOG" 2>&1 & + ) || true + for _ in $(seq 1 40); do + if port_in_use "$API_PORT"; then + listener_pids "$API_PORT" | head -1 > "$API_PID_FILE" + return 0 + fi + sleep 0.5 + done + die "后端启动超时，请查看 $API_LOG" +} + +start_web() { + if port_in_use "$WEB_PORT"; then + log "前端已在 :$WEB_PORT 运行（pid $(listener_pids "$WEB_PORT" | head -1)）" + listener_pids "$WEB_PORT" | head -1 > "$WEB_PID_FILE" + return 0 + fi + log "启动前端 :$WEB_PORT（日志 $WEB_LOG）" + ( cd "$ROOT/frontend/web" + export BACKEND_API_URL + # pnpm exec next 直接运行，避免 package.json dev 脚本自带 -p 3000 与端口参数重复 + setsid nohup pnpm exec next dev -p "$WEB_PORT" >>"$WEB_LOG" 2>&1 & + ) || true + for _ in $(seq 1 80); do + if port_in_use "$WEB_PORT"; then + listener_pids "$WEB_PORT" | head -1 > "$WEB_PID_FILE" + return 0 + fi + sleep 0.5 + done + die "前端启动超时，请查看 $WEB_LOG" +} + +# ---------- 停止 ---------- + +stop_service() { # $1 pidfile $2 port $3 名称 + local killed=0 + if pidfile_alive "$1"; then + local pid + pid="$(cat "$1")" + log "停止 $3 (pid $pid)" + kill_tree "$pid" + killed=1 + fi + local lp + for lp in $(listener_pids "$2"); do + log "停止 $3 监听进程 (pid $lp)" + kill_tree "$lp" + killed=1 + done + if [[ "$killed" == 0 ]]; then + log "$3 未在运行" + fi + for _ in $(seq 1 20); do + port_in_use "$2" || break + sleep 0.3 + done + if pidfile_alive "$1"; then kill -9 "$(cat "$1")" 2>/dev/null || true; fi + for lp in $(listener_pids "$2"); do kill -9 "$lp" 2>/dev/null || true; done + rm -f "$1" + log "$3 已停止" +} + +status() { + local api_pid web_pid + api_pid="$(listener_pids "$API_PORT" | head -1 | tr -d '\n ' || true)" + web_pid="$(listener_pids "$WEB_PORT" | head -1 | tr -d '\n ' || true)" + log "后端: ${api_pid:+运行中 pid $api_pid}${api_pid:-未运行}" + log "前端: ${web_pid:+运行中 pid $web_pid}${web_pid:-未运行}" + log "访问: 前端 http://127.0.0.1:$WEB_PORT | API http://127.0.0.1:$API_PORT/api/health" +} + +# ---------- actions ---------- + +case "${1:-start}" in + start) + start_api + start_web + status + ;; + stop) + stop_service "$API_PID_FILE" "$API_PORT" "后端" + stop_service "$WEB_PID_FILE" "$WEB_PORT" "前端" + ;; + restart) + "$0" stop + sleep 1 + "$0" start + ;; + status) + status + ;; + logs) + case "${2:-}" in + api) tail -f "$API_LOG" ;; + web) tail -f "$WEB_LOG" ;; + *) tail -f "$API_LOG" "$WEB_LOG" ;; + esac + ;; + *) + echo "用法: $0 {start|stop|restart|status|logs [api|web]}" >&2 + exit 1 + ;; +esac