44 lines
2.3 KiB
Markdown
44 lines
2.3 KiB
Markdown
# 乐活公益·暖心服务平台
|
||
|
||
V1.0 使用 TypeScript 全栈 monorepo，包含微信小程序、Web 管理后台、模块化单体 API 与共享契约。
|
||
|
||
## 环境要求
|
||
|
||
- Node.js 24 LTS
|
||
- pnpm 11
|
||
- Docker 29+ 与 Docker Compose
|
||
|
||
## 初始化
|
||
|
||
1. 复制 `.env.example` 为 `.env`，仅填写本地开发值，禁止提交真实密钥。
|
||
2. 运行 `pnpm install`。
|
||
3. 为 `SESSION_TOKEN_PEPPER`、`AUDIT_IP_HASH_KEY` 生成独立随机值，为 `FIELD_ENCRYPTION_KEY` 生成 32 字节随机值并以 Base64 保存；填写微信开发配置和精确的 `ADMIN_WEB_ORIGIN`。
|
||
4. 运行 `docker compose up -d` 启动 MySQL、Redis、MinIO。
|
||
5. 运行 `pnpm --filter @lehuo/api db:deploy` 执行 migration。
|
||
6. 首次部署时通过环境变量提供 `BOOTSTRAP_ADMIN_USERNAME`、`BOOTSTRAP_ADMIN_PASSWORD`、`BOOTSTRAP_ADMIN_DISPLAY_NAME`，运行 `pnpm --filter @lehuo/api bootstrap:admin`；已有后台凭据时命令会拒绝重复初始化。
|
||
7. 运行 `pnpm --filter @lehuo/api dev` 启动 API，健康检查地址为 `http://localhost:3000/health`，Swagger 地址为 `http://localhost:3000/api/docs`。
|
||
8. 运行 `pnpm --filter @lehuo/admin-web dev` 启动管理后台。
|
||
9. 配置小程序 API 地址后，使用微信开发者工具导入 `apps/miniprogram`。
|
||
|
||
后台会话使用 HttpOnly Cookie，不存入 localStorage；生产环境必须启用 HTTPS 并设置 `ADMIN_COOKIE_SECURE=true`。密钥和首次管理员密码不得提交到仓库。
|
||
|
||
## 质量命令
|
||
|
||
```bash
|
||
pnpm lint
|
||
pnpm typecheck
|
||
pnpm test:unit
|
||
pnpm test:integration
|
||
pnpm build
|
||
```
|
||
|
||
集成测试只允许连接数据库名为 `lehuo_test` 的 MySQL。可先运行 `docker compose --profile test up -d mysql-test`，再设置 `TEST_DATABASE_URL` 后执行测试。
|
||
|
||
项目约束、当前阶段和决策分别见 `docs/01_PROJECT_CONSTITUTION.md`、`docs/10_TASK_STATE.md`、`docs/11_DECISIONS.md`。
|
||
|
||
## Ubuntu 26.04 云服务器部署
|
||
|
||
Ubuntu 26.04 LTS 单机部署包位于 `infra/ubuntu/`，提供 Docker 官方源安装、生产环境密钥生成、双域名 TLS、私有 MySQL/Redis/MinIO、API/管理后台镜像、migration、备份恢复、冒烟和回滚脚本。完整步骤见 `infra/ubuntu/README.md`。
|
||
|
||
该部署包不替代 staging、UAT、微信合法域名/真实 AppID、隐私法务、告警接收与异地备份验收；外部项未完成前不得宣称已生产上线。
|