---
title: 开发环境
updated: 2026-04-23
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 18 | `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/`） |

### 登录凭据

```
用户名: 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))"`

### 微信小程序配置

| 配置 | 位置 | 说明 |
|------|------|------|
| 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

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

## 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（放行所有请求）
⚠️ 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 节结构，确立为连接信息的单一真相源 |