跟着下面四步,在本地打开工作台。默认使用 PostgreSQL 和 Redis,同时启动 API、网页和 Celery worker。
执行目录:仓库根目录,也就是包含 pnpm-workspace.yaml 的目录。下文命令都在这里运行。
开始前准备什么?
Section titled “开始前准备什么?”| 工具 | 要求 |
|---|---|
| Node.js | ≥ 22.13;pnpm 版本由 package.json 锁定,通过 Corepack 安装 |
| Python | ≥ 3.11,并安装 uv |
| Docker | Docker 服务已启动,能运行 docker compose |
1. 启动数据库和 Redis
Section titled “1. 启动数据库和 Redis”docker compose -f docker-compose.dev.yml up -d检查容器状态:
docker compose -f docker-compose.dev.yml ps看到什么算成功: fba_postgres 和 fba_redis 都显示 healthy。首次启动需要等健康检查完成,再继续下一步。
2. 安装依赖,准备配置
Section titled “2. 安装依赖,准备配置”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 账号。
3. 初始化开发库
Section titled “3. 初始化开发库”pnpm db:init按提示确认目标库,并给 admin 设置新密码,记下这个密码。初始化也会停用示例账号 test;自动化环境通过 FBA_INIT_ADMIN_PASSWORD 提供密码。
看到什么算成功: 最后出现「已把新库标记到迁移 head」。再检查迁移版本:
pnpm db:current输出的版本应带有 (head)。
4. 启动并登录
Section titled “4. 启动并登录”pnpm dev保持终端运行,在浏览器打开 http://127.0.0.1:8888。
按顺序检查:
- 登录页显示验证码图片,说明前后端已经连通(默认配置下验证码开启)。
- 用
admin和初始化时设置的密码登录,进入工作台。 - 刷新页面,仍然保持登录。
完成这三项,本地环境就可以用了。下次启动只需确认容器在运行,再执行 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,自动重载) | 8088 | pnpm dev |
| React(Vite) | 8888 | pnpm dev |
| Celery worker(内嵌 beat) | — | pnpm dev |
| PostgreSQL / Redis | 5432 / 6380 | docker compose |
前端固定使用 8888:CORS、OAuth2 回调和桌面端开发地址都与它对应。被占用时 Vite 会直接报错;请先确认占用进程,再决定是否停止。其他启动报错可按原文搜索常见问题。
可以换用 SQL Server、MySQL 或 S3 吗?
可以。下面是可选服务的启动方式,数据库切换还需修改 .env 中的 DATABASE_*。
| 服务 | 准备方式 |
|---|---|
| SQL Server | docker 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 生成) |