本地调试与启动

1. 环境准备

• Python 3.11（推荐 venv）+ requirements.txt 依赖
• PostgreSQL 与 Redis（本机、Docker 或远程均可）
• 前端：Node.js 18+ 与 npm
• （可选）Go 工具链用于重新构建节点二进制；调试后端通常不需要

python -m venv .venv
# Linux/macOS
source .venv/bin/activate
# Windows Git Bash
# source .venv/Scripts/activate
pip install -r requirements.txt

cp .env.example .env

2. 启动 PostgreSQL 与 Redis

最简单的方式是只启动 Compose 中的依赖，不启动应用：

docker compose up -d postgres redis
docker compose ps

这将把 PostgreSQL 映射到宿主 127.0.0.1:15432，Redis 映射到 127.0.0.1:6479。此时需要把 .env 指到这些端口：

[postgres]
host = 127.0.0.1
port = 15432
user = ai_lubricant
password = ai_lubricant
database = ai-lubricant

[redis]
host = 127.0.0.1
port = 6479
prefix_key = marsview
db = 0
decode_responses = true
max_connections = 500
stream_timeout = 30
pool_timeout = 30

3. 初始化数据库

python init_db.py

脚本连接到默认 postgres 库，若不存在则创建 ai-lubricant 数据库，然后执行 sql/init.sql 建表。重复运行是安全的（存在则跳过）。

4. 启动数据服务

# 常规
python main.py

# 调试开发模式：自动重载
uvicorn main:app --host 0.0.0.0 --port 8001 --reload

# 只监听本机
uvicorn main:app --host 127.0.0.1 --port 8001

启动成功后监听 0.0.0.0:8001（当前源码固定端口，见部署文档说明）。python main.py 没有热重载；日常改代码调试用 uvicorn ... --reload。

5. 启动节点控制服务

python -m node_server

默认监听 0.0.0.0:8003（可用 NODE_CONTROL_PORT 调整）。该服务与数据服务共享同一份 .env 和 PostgreSQL。若缺少 token/主密钥会自动生成并回写 .env，因此 .env 必须是可写文件。

仅调试 API/前端/MCP 时，可以暂时不启动节点控制服务；数据服务内部调用节点功能（任务、终端、编辑器、文件、节点出口）时才会用到它。compat 层已设计为在未配置/不可用时可降级。

6. 启动 Web 前端

cd user-frontend
npm install

# 离线/私有化版（默认首页跳到登录），开发端口 11180
npm run dev:offline

# 在线版
# npm run dev:online

Vite 默认监听 0.0.0.0:11180。开发服务器把 /api、/admin、/v1、/agent、/mcp 转发到 TARGET（.env.offline 指向 http://localhost:8001；.env.online 使用 VITE_APP_EDITION=online 并默认不设 TARGET）。如果数据服务不在本机 8001，用环境变量或对应 env 文件覆盖 TARGET。

管理端在 http://localhost:11180/manager，用户门户在 http://localhost:11180/console。

7. 移动端本地调试

移动端位于 mobile/（独立仓库，以 git submodule 挂在主仓该路径；首次需 git submodule update --init mobile），使用 Expo Router + React Native。它通过 Cookie 会话或 Basic Auth 访问同一套数据服务接口；本地调试时通常先按上文启动数据服务（8001），再让 App 指向该后端。

cd mobile
npm install

# 启动 Metro / Expo 开发服务
npm start

# 真机或模拟器调试
npm run android
npm run ios

启动后在登录页填写后端地址（例如 http://127.0.0.1:8001 或局域网 IP）。Android 模拟器访问宿主机后端时，部分环境需要用 http://10.0.2.2:8001 代替 127.0.0.1。

本地校验

cd mobile

# TypeScript 类型检查（当前仓库必须通过）
npx tsc --noEmit

# ESLint（expo 配置）
npx eslint . --no-cache

# Jest（当前 mobile/ 下暂无 *.test.ts(x) 用例，命令可用但通常没有测试可跑）
npm test -- --runInBand --silent

8. 接口探针

数据服务

# 存活
curl -s http://127.0.0.1:8001/ | head -20

# MCP 运行时健康
curl -s http://127.0.0.1:8001/mcp/health

# 模型列表（无需鉴权）
curl -s http://127.0.0.1:8001/v1/models | head -c 400; echo

节点控制服务

# 健康：包含已连接节点数
curl -s http://127.0.0.1:8003/health

前端开发代理

# 经 Vite 代理访问后端，验证 /api 与 /admin 转发
curl -s http://127.0.0.1:11180/v1/models | head -c 200; echo
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:11180/manager

9. 日志

• 数据服务文件日志：项目根 logs/ai-lubricant-YYYY-MM-DD.log，按天轮转、保留 30 天并压缩。首次启动时自动创建。
• 标准输出：启动时 loguru 也会输出到控制台。
• 日志级别：文件 sink 固定 DEBUG；system.debug 与 logging.level 影响业务日志细节。可在管理端主配置页面调整。
• 敏感字段：文件 sink 使用 diagnose=False，异常堆栈不打印变量值，避免把请求密钥写进日志。

# 跟随日志
tail -f logs/ai-lubricant-$(date +%F).log

# 只看最近错误
grep -iE 'error|traceback|exception' logs/ai-lubricant-$(date +%F).log | tail -30

10. 常见故障排查