hms/wiki/infrastructure.md

title, updated, status, tags

title	updated	status	tags
开发环境	2026-05-03	stable	infrastructure dev-environment windows postgresql

开发环境

从 index 导航。关联: erp-server database frontend testing

本页是连接信息、启动命令、登录凭据的单一真相源。 其他页面引用此处。

1. 设计决策

• Windows 原生运行 — PostgreSQL/Redis/Rust/Node 直接在宿主机，不用 Docker
• 一键启动 — dev.ps1 管理前后端生命周期
• 环境变量优先 — 敏感配置通过 ERP__ 前缀环境变量覆盖 TOML

2. 关键文件 + 连接信息

核心文件

文件	职责
dev.ps1	一键启动/停止（自动清理端口 5174-5189）
crates/erp-server/config/default.toml	默认配置模板
docker/docker-compose.yml	可选 Docker 配置

服务连接

服务	地址	用途
PostgreSQL 16	postgres://postgres:123123@localhost:5432/erp	主数据库
Redis 7	redis://:redis_KBCYJk@129.204.154.246:6379 (云端)	缓存 + 限流
后端 API	http://localhost:3000/api/v1	Axum 服务
前端 SPA	http://localhost:5174	Vite 开发服务器
微信小程序	微信开发者工具	患者端小程序（apps/miniprogram/dist/）
Ollama	http://127.0.0.1:11434	本地 AI 推理（qwen3:4b）

登录凭据

用户名: admin    密码: Admin@2026

psql: D:\postgreSQL\bin\psql.exe -U postgres -h localhost -d erp

必须设置的环境变量

变量	开发值
ERP__DATABASE__URL	postgres://postgres:123123@localhost:5432/erp
ERP__JWT__SECRET	dev-secret-key-change-in-prod
ERP__AUTH__SUPER_ADMIN_PASSWORD	Admin@2026
ERP__REDIS__URL	redis://:redis_KBCYJk@129.204.154.246:6379
ERP__WECHAT__APPID	wx20f4ef9cc2ec66c5
ERP__WECHAT__SECRET	微信小程序 Secret
ERP__WECHAT__DEV_MODE	true（开发时跳过 jscode2session，允许 DevTools 模拟器登录）
ERP__HEALTH__AES_KEY	64 字符 hex 编码（32 字节）
ERP__HEALTH__HMAC_KEY	64 字符 hex 编码（32 字节）

所有八个在 default.toml 中为 __MUST_SET_VIA_ENV__ 占位符

开发环境 AES/HMAC 密钥生成: python -c "import secrets; print(secrets.token_hex(32))"

Ollama 本地 AI 配置

启动脚本：tmp/start-ollama.ps1（必须用 ollama serve 而非 ollama app，否则环境变量不生效）

环境变量	值	说明
OLLAMA_HOST	http://127.0.0.1:11434	只监听本地（默认 0.0.0.0 暴露局域网）
OLLAMA_CONTEXT_LENGTH	4096	4b 模型足够，默认 262144 会导致 35GB+ KV cache
OLLAMA_MAX_LOADED_MODELS	1	开发环境只加载一个模型
OLLAMA_FLASH_ATTENTION	true	RTX 3070 (Ampere) 支持，降低显存占用
OLLAMA_KEEP_ALIVE	10m	模型保留 10 分钟避免频繁重载
OLLAMA_ORIGINS	http://localhost:3000,http://localhost:5174	CORS 限制
OLLAMA_NO_CLOUD	true	禁用云功能

GPU 注意事项： 默认 OLLAMA_CONTEXT_LENGTH=262144 会使 KV cache 需要 35GB+ CPU 内存 + 1.8GB GPU 显存，RTX 3070 8GB 无法加载。设为 4096 后模型可完全加载到 GPU（~3GB 显存），推理速度正常。

qwen3 thinking 模式： qwen3:4b 默认开启 thinking，流式 API 中 message.content 为空（全部 token 消耗在 thinking 上）。erp-ai Ollama provider 对 qwen3 自动改用非流式 API + strip_think_block 剥离 <think... 块。

微信小程序配置

配置	位置	说明
AppID/Secret	环境变量 ERP__WECHAT__APPID / ERP__WECHAT__SECRET	微信登录凭据
加密密钥	环境变量 TARO_APP_ENCRYPTION_KEY	小程序本地存储加密密钥
API URL	apps/miniprogram/config/index.ts defineConstants	编译时注入，默认 http://localhost:3000/api/v1
开发者工具	apps/miniprogram/project.config.json	urlCheck: false，AppID wx20f4ef9cc2ec66c5

微信凭据和加密密钥通过环境变量注入，不硬编码在源码中

集成契约

方向	模块	触发时机
提供 →	erp-server	数据库/Redis 连接
提供 →	frontend	Vite 代理目标
提供 →	testing	测试环境配置
提供 →	miniprogram	后端 API + 微信登录

3. 常用命令

Rust

cargo check                        # 编译检查
cargo test --workspace             # 运行所有测试
cargo run -p erp-server            # 启动后端服务
cargo fmt --check                  # 检查格式
cargo clippy -- -D warnings        # Lint 检查

前端

cd apps/web && pnpm install        # 安装依赖
cd apps/web && pnpm dev            # 开发模式（端口 5174）
cd apps/web && pnpm build          # 构建生产版本

数据库

PGPASSWORD=123123 "D:\postgreSQL\bin\psql.exe" -U postgres -h localhost -d erp  # 连接数据库

WASM 插件

cargo build -p erp-plugin-test-sample --target wasm32-unknown-unknown --release
wasm-tools component new target/wasm32-unknown-unknown/release/erp_plugin_test_sample.wasm -o target/erp_plugin_test_sample.component.wasm
cargo test -p erp-plugin-prototype  # 运行插件集成测试

4. 代码逻辑

一键启动（推荐）

.\dev.ps1              # 启动后端 + 前端
.\dev.ps1 -Status      # 查看端口状态
.\dev.ps1 -Stop        # 停止所有服务
.\dev.ps1 -Restart     # 重启所有服务

手动启动

# 后端（必须从 crates/erp-server 目录）
cd crates/erp-server
$env:ERP__DATABASE__URL = "postgres://postgres:123123@localhost:5432/erp"
$env:ERP__JWT__SECRET = "dev-secret-key-change-in-prod"
$env:ERP__AUTH__SUPER_ADMIN_PASSWORD = "Admin@2026"
cargo run -p erp-server

# 前端
cd apps/web && pnpm install && pnpm dev

⚡ 不变量: 后端必须从 crates/erp-server/ 目录启动或通过环境变量覆盖所有配置 ⚡ 不变量: Vite 固定端口 5174（--strictPort），前端代理 /api → 后端 3000

5. 活跃问题 + 陷阱

⚠️ Redis 不可达时限流自动降级为 fail-open 已修复： 默认 fail-close（503），可配置 ERP__RATE_LIMIT__FAIL_CLOSE=false 开发环境放行 ⚠️ Docker Compose 配置保留在 docker/ 下但日常开发不依赖 ⚠️ 首次 cargo run 编译整个 workspace 较慢（含 wasmtime），后续增量快

6. 变更记录

日期	变更
2026-04-26	从 CLAUDE.md 迁移：常用命令（§9）
2026-04-25	外部化微信凭据和健康加密密钥为环境变量；添加 4 个新的必设环境变量
2026-04-24	添加微信小程序配置信息和集成契约
2026-04-23	重构为 5 节结构，确立为连接信息的单一真相源