Kris K
7fd70c9919
* refactor: consolidate repository launchers and retire stale tooling * test: wait for source smoke broker and correct desktop entry docs * chore: exclude runtime PID metadata from repository and images
2.7 KiB
源码 Web 服务启动指南
普通用户优先使用 README 中的桌面客户端；本文用于 macOS/Linux 源码开发。容器部署见 DOCKER.md，桌面打包见 BUILD_GUIDE.md。
准备环境
使用 Python 3.11、Node.js 20、Redis，以及可用的 FFmpeg。CI 使用 Python 3.11 / Node.js 20；前端依赖只在 frontend/ 管理。
python3 -m venv venv
source venv/bin/activate
python -m pip install -r requirements.txt
(cd frontend && npm ci)
cp env.example .env
编辑 .env 配置模型与 Redis，配置项见 env.example。macOS 可用 brew install redis && brew services start redis；Linux 使用发行版服务管理器启动 Redis。远程 Redis 不可用时，启动器会报错，不会用本地 Redis 或 SQLite 替代。
启动与管理
./start_autoclip.sh # 前台运行，Ctrl+C 停止本次启动的服务
./quick_start.sh # 同一启动流程，通过健康检查后转入后台
./status_autoclip.sh # 返回非零状态表示服务缺失或检查失败
./stop_autoclip.sh # 停止当前 checkout 记录的服务及子进程
脚本从自身所在目录运行，可以从其他目录调用。后台模式也可使用 ./start_autoclip.sh --detach。默认 API 为 http://localhost:8000、Web 为 http://localhost:3000；用 BACKEND_PORT / FRONTEND_PORT 环境变量调整。启动器不会杀掉占用端口的其他进程；确认所属服务后再处理端口冲突。
运行记录保存在 backend.pid / frontend.pid / celery.pid 和对应 .pid.json，日志位于 logs/。停止前验证进程命令、工作目录与创建时间；无法确认归属会报错，不会全局查找并终止 Vite/Celery。Redis 可能被其他项目共享，停止脚本不会关闭它。
数据库由共享初始化函数创建。必要时可运行 python init_database.py，它不会清空已有数据；不要用删除数据库的方式解决启动失败。
手动开发
激活虚拟环境并配置环境变量后，分别在终端运行：
python -m uvicorn backend.main:app --host 127.0.0.1 --port 8000 --reload
celery -A backend.core.celery_app worker --loglevel=info --concurrency=1 -Q celery,processing,video,notification,upload
(cd frontend && npm run dev -- --port 3000)
手动启动的进程没有脚本 PID 记录，请在各自终端用 Ctrl+C 停止。状态脚本检查已记录进程及 API/Web/Redis 可用性；Worker 进程存活不保证某个任务已经完成，任务队列与转写进度应查看 logs/celery.log 和项目页面。