hms/wiki/infrastructure.md

title, updated, status, tags

title	updated	status	tags
开发环境	2026-05-25	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/）
小程序 H5 调试	http://localhost:10086	浏览器预览（apps/miniprogram/dist-h5/，代理到 :3000）
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/.env / .env.h5	小程序用绝对路径 http://localhost:3000/api/v1，H5 用相对路径 /api/v1
开发者工具	apps/miniprogram/project.config.json	urlCheck: false，AppID wx20f4ef9cc2ec66c5
H5 入口	apps/miniprogram/src/index.html	HtmlWebpackPlugin 模板，H5 构建必需
H5 输出	apps/miniprogram/dist-h5/	与小程序 dist/ 分离，互不影响

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

集成契约

方向	模块	触发时机
提供 →	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          # 构建生产版本

微信小程序

cd apps/miniprogram && pnpm run dev:weapp    # ✅ 开发调试（必须用这个！使用 .env 中的开发地址）
cd apps/miniprogram && pnpm run build:weapp   # 生产构建（使用 .env.production 中的生产域名，DevTools 中不可用）
cd apps/miniprogram && pnpm run dev:h5        # H5 浏览器预览（端口 10086，推荐调试用）
cd apps/miniprogram && pnpm run build:h5      # H5 生产构建

构建模式区分（重要）：

• dev:weapp → NODE_ENV=development → 加载 .env → TARO_APP_API_URL=http://192.168.31.123:3000/api/v1
• build:weapp → NODE_ENV=production → 加载 .env.production → TARO_APP_API_URL=https://api.hms.example.com/api/v1

DevTools 中调试必须用 dev:weapp，否则请求打到生产域名（无 TLS）→ ERR_SSL_PROTOCOL_ERROR → 离线抑制触发 → DevTools 卡死。这是一个已踩坑的陷阱（2026-05-25）。

调试建议： 日常 UI 开发和页面调试优先用 dev:h5（浏览器热更新 + DevTools），完成后在微信开发者工具中做最终验证。H5 模式下微信特有 API（wx.login、Taro.request 微信登录态等）不可用，但页面布局和交互可完整预览。

H5 模式通过 .env.h5 将 API URL 设为 /api/v1（相对路径），dev server 自动代理到 localhost:3000，无需处理 CORS。

数据库

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  # 运行插件集成测试

Graphify 知识图谱

python -m graphify query "BLEConnection"     # 搜索节点（比 Grep 更精准，按调用/引用关系）
python -m graphify path "A" "B"              # 两个模块间的最短路径
python -m graphify explain "ArticleDetail"   # 自然语言解释节点及其邻居
python -m graphify update .                  # 增量更新图谱（AST-only，秒级完成）

开发流程中的使用： 接手新任务时先 graphify query 定位相关代码 → graphify path 追踪调用链 → 再 Grep/Read 确认具体内容。代码改动后运行 graphify update . 保持图谱最新。详见 CLAUDE.md §graphify。

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-05-25	添加 Graphify 知识图谱工具命令（query/path/explain/update）
2026-05-25	明确 dev:weapp vs build:weapp 构建模式区分，记录 .env.production 导致 DevTools 卡死的陷阱
2026-04-26	从 CLAUDE.md 迁移：常用命令（§9）
2026-04-25	外部化微信凭据和健康加密密钥为环境变量；添加 4 个新的必设环境变量
2026-04-24	添加微信小程序配置信息和集成契约
2026-04-23	重构为 5 节结构，确立为连接信息的单一真相源