Mars

外观

常见问题 ​

环境要求检查 ​

在动手之前，先确认本机满足以下基础环境：

组件要求查看命令
Python>=3.12, <3.14（推荐 3.12）python --version
uv已安装（后端依赖与运行均通过 uv 管理）uv --version
Node^22.18.0 || ^24.0.0node --version
pnpm>=11.0.0（仓库锁定 11.7.0）pnpm --version
MySQL8.0+（默认数据库类型）mysql --version
Redis5.0+（限流、缓存、参数字典依赖）redis-cli --version

如果 node 或 pnpm 版本不符，前端会出现难以理解的类型或构建错误；建议优先使用 nvm/fnm 切换到匹配的 Node 版本，并通过 corepack enable 启用 pnpm。

后端启动失败 ​

后端通过 main.py 暴露的 typer 命令启动，标准命令为：

bash
cd backend
uv run python main.py start --env dev

启动时会依次初始化全局事件、Redis 参数缓存、数据字典缓存、定时任务调度器与请求限流器。任意一步失败都会打印 【失败】 应用初始化失败 并以非零状态退出。

数据库连接失败 ​

典型报错包含 Can't connect to MySQL server、Access denied 或 Unknown database。

排查要点：

  • 确认 backend/env/.env.dev 中的 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD、DATABASE_NAME 与实际数据库一致。
  • 确认目标库 mars-ai-studio 已创建（后端不会自动建库，仅会在库存在时建表/迁移）。
  • 若切换数据库类型，修改 DATABASE_TYPE（mysql / postgres / sqlite）。
  • 首次启动前需执行迁移：
bash
uv run python main.py upgrade --env dev

Redis 连接失败 ​

报错如 Error 111 connecting to 127.0.0.1:6379 或限流器初始化失败。

排查要点：

  • 确认 Redis 已启动，且 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 正确。
  • 项目默认使用逻辑库 REDIS_DB_NAME = 1，如该库被占用可调整。
  • 若本地没有 Redis 且为纯开发调试，可将 REDIS_ENABLE 设为 False（部分功能会降级）。

端口被占用 ​

默认后端端口为 8000，若提示 Address already in use，可修改 .env.dev 的 SERVER_PORT，或在启动前结束占用进程。

依赖或虚拟环境异常 ​

项目使用 uv 管理依赖。若遇到包缺失、版本冲突，优先执行：

bash
uv sync

如改动过 pyproject.toml，uv.lock 会自动更新；CI/生产环境可加 --frozen 严格按锁文件安装。

找不到环境配置文件 ​

配置按 ENVIRONMENT 加载 backend/env/.env.<env>（如 .env.dev、.env.prod）。若提示配置缺失或落到默认值，检查：

  • 启动命令是否带 --env dev；
  • backend/env/ 目录下是否存在对应的 .env.dev 文件（仓库已内置 dev/prod 两份）。

前端启动失败 ​

前端为 pnpm + Turborepo 的 monorepo，主应用位于 apps/web-ele。启动命令：

bash
cd frontend
pnpm install      # 首次或依赖变更后
pnpm dev:ele      # 仅启动 web-ele 应用
# 或 pnpm dev 启动仓库内全部应用

pnpm 或 Node 版本不匹配 ​

仓库在 package.json 中声明了 engines 与 packageManager，版本不符时 pnpm install 可能直接失败。preinstall 脚本也会强制要求使用 pnpm（only-allow pnpm），用 npm/yarn 安装会被拦截。

依赖安装卡住或报错 ​

  • 确保使用 pnpm 而非 npm，且版本满足 >=11.0.0。
  • 安装失败多为网络问题，可配置镜像或代理后重试。
  • 安装完成后若构建报 workspace:* 找不到，说明 monorepo 软链未生效，重新执行 pnpm install。

页面能打开但接口全部 404 / 网络错误 ​

这是前后端联调最常见的现象，本质是请求前缀与代理没有对齐。先理解请求的链路：

关键点：

  • 前端页面发出的请求路径以 VITE_GLOB_API_URL（/admin-api）开头，开发态由 Vite 代理拦截。
  • 代理重写目标为 VITE_PROXY_PREFIX（/api/v1），而后端 ROOT_PATH 同样为 /api/v1，三者必须对应。
  • 若后端不在本机或端口不同，修改 apps/web-ele/.env.development 的 VITE_BASE_URL（http://127.0.0.1:8000）。

接口返回加解密相关异常 ​

前端默认开启 API 加解密（VITE_APP_API_ENCRYPT_ENABLE=true），请求/响应会带 X-Api-Encrypt 头并使用约定的 AES 密钥。如果出现解密失败、白屏或数据异常：

  • 确认前后端加解密开关与密钥一致（见 .env 与 .env.dev）；
  • 自测接口时（如 Postman）若关闭了前端加密，需要后端也相应关闭加解密，否则无法直接联调。

登录与验证码 ​

  • 默认管理员账号见 .env.development：VITE_APP_DEFAULT_USERNAME=admin / VITE_APP_DEFAULT_PASSWORD=admin123。
  • 验证码默认关闭（VITE_APP_CAPTCHA_ENABLE=false）。若开启后一直校验失败，确认后端验证码服务与前端开关保持一致。
  • 登录报 Invalid credentials：优先核对账号密码，其次确认数据库中的用户数据已通过初始化脚本或迁移写入。

AI 模块相关 ​

AI 子系统依赖向量数据库做知识库检索。backend/env/.env.dev 中：

  • VECTOR_STORE_BACKEND 指定后端（chroma 适合本地开发，milvus 适合生产）；
  • 当使用 milvus 时，MILVUS_URI 需指向可达的 Milvus 服务（/env.dev 中的示例为内网地址，本地无该服务会导致知识库入库/检索失败）。

开发环境时，建议将 VECTOR_STORE_BACKEND 改为 chroma，无需独立服务即可跑通知识库链路。模型调用还需在模型管理中配置可用的 API_KEY 与 base_url。

通用排错清单 ​

  • 先看日志：后端启动日志会明确标注「数据库 / Redis / 调度器 / 限流器」各自的就绪状态；前端控制台（F12）可看到接口请求与响应。
  • 改完配置要重启：.env.* 在进程启动时才加载，修改后需重启对应服务。
  • 不要混用包管理器：后端用 uv，前端用 pnpm，混用会导致依赖错乱。
  • 接口文档：开发环境默认开启 Swagger（/docs）与 ReDoc（/redoc），可用于快速验证后端接口是否健康。
  • 数据库变更：模型改动后需手动生成并应用 Alembic 迁移（revision / upgrade），否则新表/字段不会生效。