跳转到内容
GitHub

快速开始

跟着下面四步,在本地打开工作台。默认使用 PostgreSQL 和 Redis,同时启动 API、网页和 Celery worker。

执行目录:仓库根目录,也就是包含 pnpm-workspace.yaml 的目录。下文命令都在这里运行。

工具要求
Node.js≥ 22.13;pnpm 版本由 package.json 锁定,通过 Corepack 安装
Python≥ 3.11,并安装 uv
DockerDocker 服务已启动,能运行 docker compose

终端窗口
docker compose -f docker-compose.dev.yml up -d

检查容器状态:

终端窗口
docker compose -f docker-compose.dev.yml ps

看到什么算成功: fba_postgres 和 fba_redis 都显示 healthy。首次启动需要等健康检查完成,再继续下一步。

终端窗口
pnpm install:all

这会安装 JavaScript 和 Python 依赖、Git 钩子以及 Playwright Chromium。命令无报错结束,且生成 apps/api/.venv 目录后,依赖就准备好了。

复制后端配置;已有 .env 时保留原文件:

终端窗口
cp -n apps/api/backend/.env.example apps/api/backend/.env

新复制的默认配置与上面的容器一致。已有配置时,请核对其中的数据库和 Redis 连接信息。

保持 DATABASE_PK_MODE='snowflake':当前种子数据使用雪花 ID,改成自增模式或漏掉这一行,会导致初始化找不到 admin 账号。

终端窗口
pnpm db:init

按提示确认目标库,并给 admin 设置新密码,记下这个密码。初始化也会停用示例账号 test;自动化环境通过 FBA_INIT_ADMIN_PASSWORD 提供密码。

看到什么算成功: 最后出现「已把新库标记到迁移 head」。再检查迁移版本:

终端窗口
pnpm db:current

输出的版本应带有 (head)。

终端窗口
pnpm dev

保持终端运行,在浏览器打开 http://127.0.0.1:8888。

按顺序检查:

  1. 登录页显示验证码图片,说明前后端已经连通(默认配置下验证码开启)。
  2. 用 admin 和初始化时设置的密码登录,进入工作台。
  3. 刷新页面,仍然保持登录。

完成这三项,本地环境就可以用了。下次启动只需确认容器在运行,再执行 pnpm dev。

为什么 admin / 123456 登录失败?

本地使用的是初始化时设置的密码。admin / 123456 只用于在线演示,初始化不允许保留种子数据里的默认密码。

本地开发能关闭验证码吗?

可以。登录后到「系统管理 → 参数配置」,将 LOGIN_CAPTCHA_ENABLED 改为 false,立即生效。数据库配置可能覆盖 .env,详见验证码配置排查。

调试时也可以用 GET /api/v1/auth/captcha 响应的 uuid 查询 Redis 中的答案:

终端窗口
docker exec fba_redis redis-cli --raw GET "fba:login:captcha:<uuid>"

各服务使用什么端口?8888 被占用怎么办?
服务端口启动方式
FastAPI(uvicorn,自动重载)8088pnpm dev
React(Vite)8888pnpm dev
Celery worker(内嵌 beat)—pnpm dev
PostgreSQL / Redis5432 / 6380docker compose

前端固定使用 8888:CORS、OAuth2 回调和桌面端开发地址都与它对应。被占用时 Vite 会直接报错;请先确认占用进程,再决定是否停止。其他启动报错可按原文搜索常见问题。

可以换用 SQL Server、MySQL 或 S3 吗?

可以。下面是可选服务的启动方式,数据库切换还需修改 .env 中的 DATABASE_*。

服务准备方式
SQL Serverdocker compose -f docker-compose.dev.yml --profile sqlserver up -d mssql;宿主机还需安装 ODBC Driver 18
MySQL自备 MySQL 8.x,设置 DATABASE_TYPE='mysql',字符集用 utf8mb4
S3 兼容存储(RustFS)docker compose -f docker-compose.dev.yml --profile s3 up -d rustfs;在存储管理中添加前先设置 STORAGE_ENCRYPT_SECRET_KEY(可用 openssl rand -hex 32 生成)

继续阅读数据库和文件存储。