8027cdd1d9
- CLAUDE.md: graphify 从英文规则扩展为中文开发流程指南 - 定义 5 种使用场景（接手任务/排查bug/理解模块/代码更新/架构审查） - 融入闭环工作法，优先级：graphify query > path > Grep/Read - wiki/index.md: 关键数字添加 Graphify 行 + 模块导航新增开发工具分区 - wiki/infrastructure.md: §3 常用命令添加 Graphify 子节
216 lines
9.4 KiB
Markdown
216 lines
9.4 KiB
Markdown
---
|
||
title: 开发环境
|
||
updated: 2026-05-25
|
||
status: stable
|
||
tags: [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
|
||
|
||
```bash
|
||
cargo check # 编译检查
|
||
cargo test --workspace # 运行所有测试
|
||
cargo run -p erp-server # 启动后端服务
|
||
cargo fmt --check # 检查格式
|
||
cargo clippy -- -D warnings # Lint 检查
|
||
```
|
||
|
||
### 前端
|
||
|
||
```bash
|
||
cd apps/web && pnpm install # 安装依赖
|
||
cd apps/web && pnpm dev # 开发模式（端口 5174）
|
||
cd apps/web && pnpm build # 构建生产版本
|
||
```
|
||
|
||
### 微信小程序
|
||
|
||
```bash
|
||
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。
|
||
|
||
### 数据库
|
||
|
||
```bash
|
||
PGPASSWORD=123123 "D:\postgreSQL\bin\psql.exe" -U postgres -h localhost -d erp # 连接数据库
|
||
```
|
||
|
||
### WASM 插件
|
||
|
||
```bash
|
||
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 知识图谱
|
||
|
||
```bash
|
||
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. 代码逻辑
|
||
|
||
### 一键启动（推荐）
|
||
|
||
```powershell
|
||
.\dev.ps1 # 启动后端 + 前端
|
||
.\dev.ps1 -Status # 查看端口状态
|
||
.\dev.ps1 -Stop # 停止所有服务
|
||
.\dev.ps1 -Restart # 重启所有服务
|
||
```
|
||
|
||
### 手动启动
|
||
|
||
```powershell
|
||
# 后端（必须从 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 节结构，确立为连接信息的单一真相源 |
|