From 6ccfa4c0eb6296ecc4a26e8a8c848535c94a4da4 Mon Sep 17 00:00:00 2001 From: gitee-bot Date: Thu, 30 Apr 2026 07:24:27 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E6=96=87=E6=A1=A3=20DEPLOY.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DEPLOY.md | 380 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 380 insertions(+) create mode 100644 DEPLOY.md diff --git a/DEPLOY.md b/DEPLOY.md new file mode 100644 index 0000000..77fea14 --- /dev/null +++ b/DEPLOY.md @@ -0,0 +1,380 @@ +# TS 酒店管理系统部署指南 + +本文档提供 TS 酒店管理系统 Web API 的完整部署指南。 + +## 目录 + +- [环境要求](#环境要求) +- [本地开发部署](#本地开发部署) +- [Docker 部署](#docker-部署) +- [生产环境部署](#生产环境部署) +- [数据库配置](#数据库配置) +- [配置说明](#配置说明) +- [健康检查](#健康检查) +- [常见问题](#常见问题) + +--- + +## 环境要求 + +| 组件 | 版本要求 | 说明 | +|------|---------|------| +| .NET SDK | 10.0+ | 运行时环境 | +| .NET Runtime | 10.0+ | 运行时环境 | +| 数据库 | MariaDB 10.11+ / MySQL 5.7+ / PostgreSQL 13+ / SQL Server 2022+ | 任选其一 | +| Docker | 20.10+ | 容器化部署时需要 | +| Docker Compose | 2.0+ | 容器化部署时需要 | + +--- + +## 本地开发部署 + +### 1. 克隆项目 + +```bash +git clone https://gitee.com/java-and-net/topsky-hotel-management-system-web-api.git +cd topsky-hotel-management-system-web-api +``` + +### 2. 配置数据库 + +编辑 `EOM.TSHotelManagement.API/appsettings.json`： + +```json +{ + "DefaultDatabase": "MariaDB", + "ConnectionStrings": { + "MariaDB": "Server=localhost;Database=tshoteldb;User=root;Password=123456;", + "MySql": "Server=localhost;Database=tshoteldb;User=root;Password=123456;", + "PgSql": "Host=localhost;Database=tshoteldb;User=postgres;Password=123456;", + "SqlServer": "Server=localhost;Database=tshoteldb;User=sa;Password=YourPassword;" + }, + "InitializeDatabase": true, + "Jwt": { + "Key": "your-256-bit-secret-key-here-min-32-chars", + "ExpiryMinutes": 20 + }, + "DataProtection": { + "Key": "your-dataprotection-key-here" + } +} +``` + +**配置说明：** +- `DefaultDatabase`：选择数据库类型，可选值：`MariaDB`、`MySql`、`PgSql`、`SqlServer` +- `InitializeDatabase`：首次运行设为 `true` 自动创建数据库和表结构，后续可设为 `false` +- `Jwt__Key`：用于生成 Token 的密钥，至少 32 个字符 +- `DataProtection`：用于敏感数据加解密的密钥 + +### 3. 使用 Visual Studio 部署 + +1. 使用 Visual Studio 2026 打开 `EOM.TSHotelManagement.Web.sln` +2. 设置 `EOM.TSHotelManagement.API` 为启动项目 +3. 按 F5 启动调试 + +### 4. 使用命令行部署 + +```bash +cd EOM.TSHotelManagement.API +dotnet restore +dotnet run +``` + +服务启动后访问：`http://localhost:8080/swagger` + +--- + +## Docker 部署 + +### 方式一：使用 Docker Compose（推荐） + +#### 1. 准备环境变量文件 + +```bash +cp .env.example .env +``` + +#### 2. 编辑 .env 文件 + +```env +# 镜像配置 +TSHOTEL_IMAGE=yjj6731/tshotel-management-system-api:latest +CONTAINER_NAME=tshotel-api +API_HOST_PORT=63001 + +# 应用配置 +ASPNETCORE_ENVIRONMENT=docker +DefaultDatabase=MariaDB +InitializeDatabase=false + +# 数据库连接（根据 DefaultDatabase 选择一个配置） +MARIADB_CONNECT_STR=Server=mariadb;Database=tshoteldb;User=root;Password=123456; +# MySqlConnectStr=Server=mysql;Database=tshoteldb;User=root;Password=123456; +# PgSqlConnectStr=Host=postgres;Database=tshoteldb;User=postgres;Password=123456; + +# 安全配置 +JWT_SIGNING_KEY=your-256-bit-secret-key-here-min-32-chars + +# 邮件服务（如需启用） +Mail__Enabled=false +MAIL_PASSWORD=your-mail-password +``` + +#### 3. 启动服务 + +```bash +# 启动 +docker compose up -d + +# 查看日志 +docker compose logs -f tshotel-api + +# 停止 +docker compose down +``` + +### 方式二：使用 docker run + +```bash +docker run -d \ + --name tshotel-api \ + --env-file .env \ + -v /app/config:/app/config \ + -v /app/keys:/app/keys \ + -p 63001:8080 \ + yjj6731/tshotel-management-system-api:latest +``` + +### Docker 部署参数说明 + +| 参数名称 | 说明 | 必填 | 默认值 | 可选值 | +|---------|------|-----|-------|--------| +| `DefaultDatabase` | 默认数据库 | Y | - | MariaDB/MySql/SqlServer/PgSql | +| `ASPNETCORE_ENVIRONMENT` | 系统环境 | Y | docker | docker | +| `{数据库}ConnectStr` | 数据库连接字符串 | Y | - | - | +| `Jwt__Key` | JWT 密钥 | Y | - | 至少32位字符 | +| `Jwt__ExpiryMinutes` | Token 有效时间(分钟) | Y | 20 | - | +| `Lsky__Enabled` | 是否启用兰空图床 | Y | false | true/false | +| `Mail__Enabled` | 是否启用邮件服务 | Y | true | true/false | +| `Mail__Host` | 邮箱 SMTP 地址 | Y | smtp.example.com | - | +| `Mail__Port` | 邮箱 SMTP 端口 | Y | 465 | - | +| `Mail__EnableSsl` | 是否启用 SSL | Y | true | true/false | +| `InitializeDatabase` | 初始化数据库 | N | true | true/false | +| `Redis__Enabled` | 是否启用 Redis | N | false | true/false | +| `Idempotency__Enabled` | 是否启用幂等键 | N | true | true/false | + +--- + +## 生产环境部署 + +### 1. 安全建议 + +- **不要**在配置文件中明文存储密码，使用环境变量或 Docker Secrets +- **务必**修改默认的 JWT 密钥和 Data Protection 密钥 +- 启用 HTTPS 并配置 SSL 证书 +- 配置防火墙规则，限制访问来源 +- 定期备份数据库 + +### 2. Nginx 反向代理配置示例 + +```nginx +server { + listen 443 ssl; + server_name api.yourdomain.com; + + ssl_certificate /path/to/ssl/certificate.crt; + ssl_certificate_key /path/to/ssl/private.key; + + location / { + proxy_pass http://localhost:63001; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection keep-alive; + proxy_set_header Host $host; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + proxy_cache_bypass $http_upgrade; + } +} +``` + +### 3. Docker 部署生产环境 + +```bash +# 拉取最新镜像 +docker pull yjj6731/tshotel-management-system-api:latest + +# 使用生产环境变量文件 +docker run -d \ + --name tshotel-api-prod \ + --restart=always \ + --env-file .env.production \ + -v /app/keys:/app/keys \ + -p 63001:8080 \ + yjj6731/tshotel-management-system-api:latest +``` + +--- + +## 数据库配置 + +### 支持的数据库 + +| 数据库 | 版本要求 | 建库建表支持 | +|-------|---------|-------------| +| MariaDB | 10.11+ | ✅ | +| MySQL | 5.7+ | ✅ | +| PostgreSQL | 13+ | ✅ | +| SQL Server | 2022+ | ✅ | + +### 初始化数据库 + +首次部署时，设置 `InitializeDatabase: true` 会自动创建数据库和表结构。 + +### 手动建库建表 + +如需手动建库，可使用项目提供的数据库脚本： + +``` +数据库脚本/ +├── MariaDB版本/ +├── MySQL版本/ +└── PostgreSQL版本/ +``` + +--- + +## 配置说明 + +### 应用程序配置 (appsettings.json) + +```json +{ + "Logging": { + "LogLevel": { + "Default": "Information", + "Microsoft": "Warning" + } + }, + "AllowedHosts": "*", + "DefaultDatabase": "MariaDB", + "ConnectionStrings": { + "MariaDB": "Server=localhost;Database=tshoteldb;User=root;Password=123456;" + }, + "InitializeDatabase": true, + "Jwt": { + "Key": "your-256-bit-secret-key-here-min-32-chars", + "ExpiryMinutes": 20 + }, + "DataProtection": { + "Key": "your-dataprotection-key" + }, + "AllowedOrigins": [ + "http://localhost:8080", + "https://www.yourdomain.com" + ], + "ExpirationSettings": { + "NotifyDaysBefore": 3, + "CheckIntervalMinutes": 5 + }, + "Idempotency": { + "Enabled": true, + "EnforceKey": false, + "MaxKeyLength": 128, + "InProgressTtlSeconds": 120, + "CompletedTtlHours": 24, + "PersistFailureResponse": false + }, + "Mail": { + "Enabled": false, + "Host": "smtp.example.com", + "UserName": "admin@example.com", + "Port": 465, + "EnableSsl": true, + "DisplayName": "TSHotel" + }, + "Redis": { + "Enabled": false, + "ConnectionString": "", + "DefaultDatabase": 0 + }, + "Lsky": { + "Enabled": false, + "BaseAddress": "", + "Email": "", + "Password": "", + "UploadApi": "", + "GetTokenApi": "" + }, + "JobKeys": [ + "ReservationExpirationCheckJob", + "MailServiceCheckJob", + "RedisServiceCheckJob" + ] +} +``` + +--- + +## 健康检查 + +服务部署后，可通过以下地址进行健康检查： + +- 本地：`http://localhost:8080/health` +- Docker：`http://localhost:63001/health` + +--- + +## 常见问题 + +### Q1: 首次启动显示数据库连接失败？ + +- 检查数据库是否已启动 +- 确认连接字符串是否正确 +- 将 `InitializeDatabase` 设为 `true` 自动创建数据库 + +### Q2: JWT Token 验证失败？ + +- 确认 `Jwt__Key` 配置正确且不少于 32 个字符 +- 检查 Token 是否过期 + +### Q3: 如何启用邮件通知？ + +1. 设置 `Mail__Enabled: true` +2. 配置邮件相关参数（Host、Port、UserName、Password 等） +3. 重启服务 + +### Q4: 如何使用兰空图床？ + +1. 部署兰空图床服务 +2. 设置 `Lsky__Enabled: true` +3. 配置兰空图床的 API 地址和账户信息 + +### Q5: Docker 容器无法启动？ + +```bash +# 查看容器日志 +docker logs tshotel-api + +# 检查环境变量 +docker exec tshotel-api env +``` + +### Q6: 如何升级版本？ + +```bash +# 拉取新镜像 +docker pull yjj6731/tshotel-management-system-api:latest + +# 重启容器 +docker compose down +docker compose up -d +``` + +--- + +## 相关链接 + +- [项目首页](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api) +- [API 文档](http://localhost:8080/swagger)（部署后访问） +- [问题反馈](https://gitee.com/java-and-net/topsky-hotel-management-system-web-api/issues) -- Gitee