本地部署与自托管

本文档用于说明如何在本地启动 Bondings Ink 的后端与 WebApp，并说明当前代码中的关键环境变量与验证方式。如果你只是想了解产品本身，请先看仓库根目录的 README.md。这篇更适合 开发者、想自托管的用户、以及需要联调前后端与设备流程的人。

1. 适用场景

本页主要面向以下场景：

本地开发与调试
自己部署一套后端 + WebApp
联调刷机、配置、预览和 API

2. 当前项目结构

仓库当前主要包含三部分：

backend/：FastAPI 后端，负责配置、渲染、天气、模式管理、统计等
webapp/：Next.js Web 应用，负责官网、在线刷机、登录、设备配置、在线预览
firmware/：ESP32 固件（PlatformIO / Arduino）

3. 环境要求

后端

Python 3.10+
pip

前端

Node.js 20+（推荐）
npm

固件（可选）

PlatformIO

4. 后端启动

cd backend

pip install -r requirements.txt
python scripts/setup_fonts.py

cp .env.example .env
# 按需填写环境变量

python -m uvicorn api.index:app --host 0.0.0.0 --port 8080

后端环境变量

后端示例环境变量在：backend/.env.example

当前代码中最重要的变量包括：

DEEPSEEK_API_KEY
DASHSCOPE_API_KEY
MOONSHOT_API_KEY
DEBUG_MODE
DEFAULT_CITY
DB_PATH
ADMIN_TOKEN

说明：

如果用户没有在个人中心配置自己的模型与 API Key，后端会回退到环境变量中的平台级 Key。
DEFAULT_CITY 是系统级天气默认城市，默认为 杭州。

5. WebApp 启动

cd webapp

cp .env.example .env
npm install
npm run dev

WebApp 环境变量

前端示例环境变量在：webapp/.env.example

当前主要变量：

INKSIGHT_BACKEND_API_BASE=http://127.0.0.1:8080
NEXT_PUBLIC_FIRMWARE_API_BASE=（可选）

建议本地开发时保持：

后端：http://127.0.0.1:8080
前端：http://127.0.0.1:3000

6 移动端（Expo）启动

移动端工程位于：bondings-ink-mobile/，使用 Expo（expo-router）开发。

安装依赖

cd bondings-ink-mobile
npm install

启动命令（package.json scripts）

启动开发模式（Metro）：

cd bondings-ink-mobile
npm run start

启动 Web（浏览器）：

cd bondings-ink-mobile
npm run web

启动 Android（需要本机 Android 环境/设备）：

cd bondings-ink-mobile
npm run android

启动 iOS（需要 macOS/Xcode）：

cd bondings-ink-mobile
npm run ios

常用补充（不在 scripts，但可直接运行）

指定 dev server 端口（避免与后端端口混淆/冲突）：

cd bondings-ink-mobile
npx expo start --port 19006

Web 模式下同样指定端口：

cd bondings-ink-mobile
npx expo start --web --port 19006

移动端环境变量（重点）

移动端的 .env 中常用：

EXPO_PUBLIC_INKSIGHT_API_BASE: 移动端请求后端 API 的基地址（代码会自动补上 /api 后缀）。

说明：

该变量只影响移动端向后端发起的 HTTP 请求（例如 ${EXPO_PUBLIC_INKSIGHT_API_BASE}/api/...）。
它不会决定 Expo/Metro/Web 开发服务监听的端口；Expo dev server 端口由 expo start 的 --port 控制（默认 8081）。

6. 本地入口

启动完成后，通常使用以下入口：

入口	地址	说明
WebApp	`http://127.0.0.1:3000`	官网、本地开发、在线刷机、登录、设备配置、预览
Backend API	`http://127.0.0.1:8080`	FastAPI 接口
兼容预览接口	`http://127.0.0.1:8080/api/preview?persona=WEATHER`	模式级调试入口

后端仍保留一些兼容页面（如旧版配置页、仪表盘、编辑器），但当前推荐统一从 WebApp 的设备配置页进入配置流程。

7. 账号、模型与 API Key

当前代码中：

设备配置页 负责：
- 模式选择
- 个性化设置
- 共享成员
- 状态查看
个人中心 负责：
- 文本模型提供商 / 模型 / API Key
- 图像模型提供商 / 模型 / API Key
- 免费额度与访问模式

也就是说，模型与 API Key 配置不在设备配置页，而在个人中心。

8. 固件本地编译（可选）

如果你需要本地编译或烧录固件：

cd firmware
pio run
pio run --target upload
pio device monitor

默认环境为：

epd_42_wsv2_ssd1683_c3_promini

更多硬件组合请参考：

firmware/platformio.ini
docs/hardware.md

9. 常用检查命令

后端

cd backend
pytest

前端

cd webapp
npm run lint
npx tsc --noEmit

10. 常见问题

字体下载 / Next.js 构建问题

当前 WebApp 使用 next/font 拉取在线字体。如果执行 npm run build 时网络无法访问 Google Fonts，构建可能失败。

这类问题不会影响日常 npm run dev 开发，但在离线或受限网络环境下需要额外处理。

端口冲突

前端默认 3000
后端默认 8080

如果端口被占用，请修改启动命令中的端口并同步更新 INKSIGHT_BACKEND_API_BASE。

API 调用失败

优先检查：

后端 .env 是否已填写平台级 API Key
是否已在个人中心中配置个人模型与 API Key
后端日志中是否有鉴权、额度或上游接口错误

11. 数据库后端（高级 / 实验路径）

Bondings Ink 当前的主路径是 SQLite，开发、测试与 CI 都跑在 aiosqlite + inksight.db。后端代码同时保留了一条 Postgres 旁路（backend/core/db_pg.py + backend/core/db_translator.py），通过运行时 SQL 翻译把同一份 SQLite 风格的查询转译成 PostgreSQL 方言。

要进入 PG 路径，设置以下任一环境变量即可（按优先级匹配）：

DATABASE_URL
POSTGRES_URL
POSTGRES_PRISMA_URL
POSTGRES_URL_NON_POOLING（Vercel Postgres 自动导出）

启动时后端会检查一次配置：命中 PG URL 时在日志中输出一条 WARNING，提示这条路径仍属实验性。具体连接分发在每次 get_main_db() / get_cache_db() 调用时按当前 env 决定，没有进程级"锁定"。

注意事项

CI 不跑 PG：所有自动测试都跑在 SQLite 上。新增 SQL 时无法在 CI 阶段发现 translator 兼容问题，只有在真正部署到 PG 环境下才会暴露。
没有生产 PG 部署：截止目前项目尚未把 PG 路径放到真实生产环境跑过完整流程，因此 PG 旁路视为实验性——可用于一次性验证、贡献者本地调试、Vercel Preview 实验，不应被当作已生产验证的目标。
新增 SQL 时：建议默认按 SQLite 习惯写，并复核 backend/core/db_translator.py 是否覆盖你的语法（占位符、 INSERT OR REPLACE、PRAGMA table_info(...)、datetime('now') 等）。Schema 迁移建议走 core/schema_helpers.add_column_if_missing 之类的 dialect-aware helper。

如果未来项目移到 PG-first，本节会被替换为正式部署指南。