erp/wiki/infrastructure.md

infrastructure (开发环境)

设计思想

开发环境在 Windows 宿主机直接运行所有服务：

• PostgreSQL 通过 Windows 原生安装运行
• Redis 7+ 通过 Windows 原生安装运行（可选，缺省时限流降级为 fail-open）
• 后端 Rust 服务通过 cargo run 快速重启
• 前端 Vite 热更新直接在宿主机
• PowerShell 脚本 (dev.ps1) 提供一键启动/停止

Docker Compose 配置保留在 docker/ 目录下，可供需要容器化环境的场景使用，但日常开发不依赖 Docker。

本机环境实际配置

重要：以下为当前开发机的实际配置，以本文件为准。

组件	安装路径	配置
PostgreSQL 18	D:\postgreSQL\	服务名 postgresql-x64-18, 端口 5432
Redis	云端实例	redis://:redis_KBCYJk@129.204.154.246:6379, 限流中间件已正常工作
Rust	stable (cargo in PATH)	workspace 根目录编译
Node.js + pnpm	in PATH	apps/web/

数据库连接

用户: postgres
密码: 123123
数据库: erp
连接串: postgres://postgres:123123@localhost:5432/erp

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

后端启动命令

后端必须从 crates/erp-server/ 目录启动（需要读取 config/default.toml），或通过环境变量覆盖：

# 方式一：从 crates/erp-server 目录启动（使用 default.toml + 环境变量覆盖）
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

# 方式二：一键启动脚本（推荐）
.\dev.ps1

登录凭据

用户名: admin
密码: Admin@2026

服务端口

服务	端口	用途
PostgreSQL 18	5432	主数据库
Redis 7+	6379 (云端)	缓存 + 限流
erp-server (Axum)	3000	后端 API
Vite dev server	5174	前端 SPA（固定端口，--strictPort）

连接信息（配置文件版本）

PostgreSQL: postgres://postgres:123123@localhost:5432/erp
Redis:      redis://:redis_KBCYJk@129.204.154.246:6379  (云端实例)

一键启动

.\dev.ps1              # 启动后端 + 前端（自动清理旧进程 5174-5189）
.\dev.ps1 -Status      # 查看端口状态
.\dev.ps1 -Stop        # 停止所有服务
.\dev.ps1 -Restart     # 重启所有服务

dev.ps1 会在启动前清理端口 5174-5189 范围内所有残留进程，并使用 --strictPort 确保 Vite 固定在 5174 端口。

环境变量

必须通过环境变量设置的值（default.toml 中为占位符）：

变量	说明	开发值
ERP__DATABASE__URL	数据库连接串	postgres://postgres:123123@localhost:5432/erp
ERP__JWT__SECRET	JWT 签名密钥	自定义字符串
ERP__AUTH__SUPER_ADMIN_PASSWORD	admin 初始密码	Admin@2026
ERP__REDIS__URL	Redis 连接串	redis://:redis_KBCYJk@129.204.154.246:6379

所有四个变量在 default.toml 中都是 __MUST_SET_VIA_ENV__ 占位符，必须通过环境变量设置，否则服务拒绝启动。

关联模块

• erp-server — 连接 PostgreSQL 和 Redis
• database — 迁移在 PostgreSQL 中执行
• frontend — Vite 代理 API 到后端
• testing — 测试环境详细指南

关键文件

文件	职责
dev.ps1	一键启动/停止脚本（自动清理端口 5174-5189）
docker/docker-compose.yml	可选的 Docker Compose 配置
crates/erp-server/config/default.toml	默认配置模板（密钥为占位符）
D:\postgreSQL\bin\psql.exe	PostgreSQL 客户端

常用命令

# 一键启动（推荐）
.\dev.ps1

# 手动启动后端（从 crates/erp-server 目录）
cd crates/erp-server
$env:ERP__DATABASE__URL="postgres://postgres:123123@localhost:5432/erp"
$env:ERP__JWT__SECRET="dev-secret"
$env:ERP__AUTH__SUPER_ADMIN_PASSWORD="Admin@2026"
cargo run -p erp-server

# 手动启动前端（固定端口）
cd apps/web && pnpm dev -- --strictPort

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

# 健康检查
curl http://localhost:3000/api/v1/health

# 登录测试
curl -s http://localhost:3000/api/v1/auth/login -H "Content-Type: application/json" -d '{"username":"admin","password":"Admin@2026"}'