快速开始
前置环境
- Python 3.11+。前端使用 Node.js 24.14.1 与 npm 11.8.0；Wiki Pages 工作流使用 Node.js 20。
- 可选 Redis 6+，用于登录限流和会话缓存。
- 需要 Git 和 Docker，若使用 Compose 还要保证镜像可拉取、依赖可安装。
克隆与环境变量
bash
git clone https://github.com/hzb666/LabStorageManager.git
cd LabStorageManager以 .env.example 为模板准备本地运行配置，至少确认这些配置项：
powershell
Copy-Item .env.example .env非 PowerShell 环境可使用：
bash
cp .env.example .envDEFAULT_ADMIN_PASSWORDENVCORS_ORIGINSDATABASE_URLQUERY_LOG_DIRREDIS_HOSTALGORITHMPRIVATE_KEY_PATHPUBLIC_KEY_PATH
实验步骤查库存需要配置 LLM_ENABLED=true、LLM_API_BASE_URL、LLM_API_KEY 和 LLM_MODEL。Sentry 为可选能力，前后端 DSN 为空时保持停用。
Redis 仅监听本机或 Compose 内网时，REDIS_PASSWORD 可以留空。 默认登录态为 7 天：ACCESS_TOKEN_EXPIRE_MINUTES=10080，SESSION_EXPIRE_HOURS=168。单个后端进程的 Redis 连接池上限由 REDIS_MAX_CONNECTIONS 控制，默认 100。
本地 .env.example 默认使用 sqlite:///./lab_inventory.db 和 logs。Docker Compose 会覆盖为 /data/lab_inventory.db 和 /data/logs，上传资源目录对应 /data/static，外部访问路径是 /static/。
启动后端
bash
poetry install
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000- 开发模式下可访问
http://localhost:8000/docs、/redoc和/health；安全运行模式下默认只保留业务接口和健康检查。
启动前端
bash
cd frontend
npm ci
npm run dev- 开发模式默认监听 5173。
- 前端 API 基址通常由
VITE_API_URL指向http://localhost:8000/api。 npm run dev和npm run build会先生成 RDKit 与本地字体的带版本号资源映射。- Ketcher 三个包固定使用同一版本，依赖调整后需要由 npm 重新生成
package-lock.json。 - 生产构建使用
npm run build。 - 浏览器插件构建使用
npm run build:extension，该命令会根据插件运行配置生成manifest.json和shared/generated-config.js。
Docker Compose 运行整套服务
bash
APP_PORT=80 docker compose up -d --buildbackend、frontend和redis会一起启动。- Compose 持久化 volume 需要可写，用于
/data/lab_inventory.db、/data/logs、/data/static和/data/keys。 - 可用
docker compose logs backend和docker compose logs frontend查看日志。
首次启动的自动初始化
- 后端
lifespan会调用init_db()，完成建表、索引、FTS 和默认管理员初始化。 - SQLite 连接会强制使用 WAL 和外键约束。
- 开发模式下若缺少 RSA key，配置层会尝试生成临时密钥；生产模式仍应显式提供密钥文件。
- 前端首次加载会恢复登录态，并初始化路由守卫和全局 UI 容器。
核心验证
curl http://localhost:${APP_PORT:-80}/health- 浏览器访问
http://localhost:${APP_PORT:-80}，确认前端能正常加载。 - 登录后检查
/api/users/me。 - 打开
/docs和/redoc，确认文档入口可用。 - 检查
/cart-import?import=true是否能被浏览器插件桥接。 - 检查
/static/下的上传图片或模板资源能否正常访问。 - Redis 无密码时执行
redis-cli ping；有密码时执行redis-cli -a <REDIS_PASSWORD> ping
常见排障命令
bash
docker compose ps
docker compose logs --tail 200 backend
docker compose logs --tail 200 frontend
docker compose exec redis redis-cli ping
curl -i http://localhost:8000/health文档站
wiki/ 是 VitePress 文档站源码，启动方式如下：
bash
cd wiki
npm ci
npm run dev浏览器访问 http://localhost:5174 即可查看文档站。