自动构建
This commit is contained in:
@@ -58,19 +58,27 @@ dotnet publish src/Jiaowu.Api -c Release -o .artifacts/publish
|
||||
|
||||
如需在特殊流水线中跳过自动前端构建，可传入 `-p:BuildFrontendOnPublish=false`。
|
||||
|
||||
将发布包复制到目标服务器后，再通过 Windows 服务、容器编排平台或密钥管理系统，
|
||||
为 **应用运行进程** 注入配置。下面仅演示在当前 PowerShell 会话中配置；变量只对该
|
||||
会话及其启动的子进程生效：
|
||||
将发布包复制到目标服务器后，把发布包中的 `.env.example` 复制为 `.env`，并填写
|
||||
真实配置。应用会在启动时自动读取**可执行文件所在目录**的 `.env`：
|
||||
|
||||
```powershell
|
||||
$env:ASPNETCORE_ENVIRONMENT = 'Production'
|
||||
$env:Database__Provider = 'MySql'
|
||||
$env:Jwt__Key = '至少32字节的随机生产密钥'
|
||||
$env:AllowedHosts = 'jiaowu.example.edu.cn'
|
||||
$copyParams = @{
|
||||
LiteralPath = '.artifacts\publish\.env.example'
|
||||
Destination = '.artifacts\publish\.env'
|
||||
}
|
||||
Copy-Item @copyParams
|
||||
```
|
||||
|
||||
这些值由 `Jiaowu.Api` 在每次启动时读取。不要把真实连接串或密钥写入仓库中的
|
||||
`appsettings*.json`，证书路径也必须是目标服务器上的实际路径。
|
||||
`.env` 使用 `KEY=VALUE` 格式，允许空行、以 `#` 开头的注释、可选的 `export` 前缀，
|
||||
以及单引号或双引号值。双引号值支持 `\n`、`\r`、`\t`、`\\` 和 `\"`；不执行变量
|
||||
替换或命令。真实进程环境变量的优先级高于 `.env`，因此 Windows 服务、Docker、
|
||||
Kubernetes 或密钥管理系统仍可覆盖文件中的值。
|
||||
|
||||
如需把配置文件放到其他位置，通过 `JIAOWU_ENV_FILE` 指定绝对路径；相对路径按进程
|
||||
当前工作目录解析。显式指定但文件不存在、行格式错误或引号没有闭合时，应用会拒绝
|
||||
启动。不要把真实 `.env` 提交到仓库或打进发布包；Linux/macOS 建议设置权限
|
||||
`chmod 600 .env`，Windows 应通过 ACL 只允许服务账号和管理员读取。连接串中的证书
|
||||
路径必须是运行服务器上的实际路径。
|
||||
|
||||
数据库应明确使用 `utf8mb4`；MySQL 8.4 的默认排序规则为
|
||||
`utf8mb4_0900_ai_ci`。新建数据库时可执行：
|
||||
@@ -81,18 +89,19 @@ CREATE DATABASE `jiaowu`
|
||||
COLLATE utf8mb4_0900_ai_ci;
|
||||
```
|
||||
|
||||
首次部署或版本升级时，先在目标服务器设置具备 DDL 权限的迁移账号连接串，并单独
|
||||
执行迁移：
|
||||
首次部署或版本升级时，从 `.env` 复制一份不纳入版本控制的 `.env.migrate`，只将
|
||||
连接串改成具备 DDL 权限的迁移账号，然后单独执行迁移：
|
||||
|
||||
```powershell
|
||||
$env:ConnectionStrings__MySql = 'Server=db.example.edu.cn;Port=3306;Database=jiaowu;User=MIGRATION_USER;Password=MIGRATION_PASSWORD;SslMode=VerifyFull;SslCa=C:\certs\mysql-ca.pem;'
|
||||
$env:JIAOWU_ENV_FILE = (Resolve-Path -LiteralPath '.artifacts\publish\.env.migrate').Path
|
||||
& '.artifacts\publish\Jiaowu.Api.exe' --migrate-only
|
||||
```
|
||||
|
||||
迁移成功后，将连接串替换为仅具备应用所需 DML 权限的运行账号，再启动服务：
|
||||
迁移成功后删除 `.env.migrate`，清除 `JIAOWU_ENV_FILE`，应用便会读取发布目录中的
|
||||
`.env`；其中应配置仅具备应用所需 DML 权限的运行账号：
|
||||
|
||||
```powershell
|
||||
$env:ConnectionStrings__MySql = 'Server=db.example.edu.cn;Port=3306;Database=jiaowu;User=APP_USER;Password=APP_PASSWORD;SslMode=VerifyFull;SslCa=C:\certs\mysql-ca.pem;'
|
||||
Remove-Item -LiteralPath 'Env:JIAOWU_ENV_FILE'
|
||||
& '.artifacts\publish\Jiaowu.Api.exe'
|
||||
```
|
||||
|
||||
@@ -108,19 +117,13 @@ $env:ConnectionStrings__MySql = 'Server=db.example.edu.cn;Port=3306;Database=jia
|
||||
|
||||
如需验证 Production 配置和 MySQL 8.4 部署链路，请新建专用的空数据库（例如
|
||||
`jiaowu_demo`），不要向准备承载真实业务的数据库插入演示数据。先按前述步骤执行
|
||||
`--migrate-only`，停止该环境的应用实例，再改用应用运行账号执行：
|
||||
`--migrate-only`，停止该环境的应用实例，再从 `.env.example` 复制并编辑
|
||||
`.env.demo`，配置演示数据库、运行账号和临时管理员：
|
||||
|
||||
```powershell
|
||||
$env:ConnectionStrings__MySql = 'Server=db.example.edu.cn;Port=3306;Database=jiaowu_demo;User=APP_USER;Password=APP_PASSWORD;SslMode=VerifyFull;SslCa=C:\certs\mysql-ca.pem;'
|
||||
$env:SeedAdmin__UserName = 'demo-admin'
|
||||
$env:SeedAdmin__Password = '请替换为演示环境专用的强密码'
|
||||
$env:SeedAdmin__DisplayName = '演示环境管理员'
|
||||
|
||||
$env:JIAOWU_ENV_FILE = (Resolve-Path -LiteralPath '.artifacts\publish\.env.demo').Path
|
||||
& '.artifacts\publish\Jiaowu.Api.exe' --seed-demo-data --confirm-production-demo-data
|
||||
|
||||
Remove-Item -LiteralPath 'Env:SeedAdmin__UserName'
|
||||
Remove-Item -LiteralPath 'Env:SeedAdmin__Password'
|
||||
Remove-Item -LiteralPath 'Env:SeedAdmin__DisplayName'
|
||||
Remove-Item -LiteralPath 'Env:JIAOWU_ENV_FILE'
|
||||
```
|
||||
|
||||
该命令仅允许在非 Development 环境运行，且必须同时提供确认参数。它会再次检查迁移
|
||||
@@ -155,6 +158,68 @@ SQLite 只用于本地开发：新库通过 `EnsureCreated` 建立，已有开
|
||||
- `/health/live`：只检查进程存活。
|
||||
- `/health`、`/health/ready`：实际检查数据库连接，失败时返回 HTTP 503。
|
||||
|
||||
## 跨平台发布与 Docker
|
||||
|
||||
`.gitea/workflows/publish.yml` 只在推送 `v*` 标签或手动运行时执行，普通分支 push
|
||||
不会触发耗时发布。默认生成以下自包含程序包，目标服务器无需另装 .NET：
|
||||
|
||||
- Windows x64：`.zip`
|
||||
- Linux x64、Linux ARM64：`.tar.gz`
|
||||
- `SHA256SUMS`：所有压缩包的 SHA-256 校验值
|
||||
|
||||
手动运行时启用 `include_extended_platforms`，还会生成 Windows ARM64、macOS x64
|
||||
和 macOS ARM64。Windows 使用 `Jiaowu.Api.exe` 启动，Linux/macOS 使用
|
||||
`./Jiaowu.Api`；各压缩包都包含 `.env.example`。
|
||||
|
||||
工作流同时使用 Buildx 构建 `linux/amd64`、`linux/arm64` 镜像并推送至 Gitea
|
||||
Container Registry：
|
||||
|
||||
```text
|
||||
git.biss.click/biss/academic-affairs-system
|
||||
```
|
||||
|
||||
仓库的 Actions 权限必须允许内置 `GITEA_TOKEN` 写入 Packages 和 Releases。版本标签
|
||||
会创建 Gitea Release；手动运行只保留工作流产物并推送
|
||||
`manual-<run-number>`、`sha-<commit>` 镜像标签。
|
||||
|
||||
本地使用 Docker 时，先复制并编辑配置：
|
||||
|
||||
```powershell
|
||||
Copy-Item -LiteralPath '.env.docker.example' -Destination '.env.docker'
|
||||
```
|
||||
|
||||
先使用迁移账号配置文件执行迁移，再使用应用账号配置文件启动容器；MySQL CA 文件通过
|
||||
只读卷挂载，不会进入镜像：
|
||||
|
||||
```powershell
|
||||
$image = 'git.biss.click/biss/academic-affairs-system:1.0.0'
|
||||
|
||||
$migrateArgs = @(
|
||||
'run', '--rm'
|
||||
'--env-file', '.env.docker.migrate'
|
||||
'--mount', 'type=bind,source=C:\certs\mysql-ca.pem,target=/run/secrets/mysql-ca.pem,readonly'
|
||||
$image
|
||||
'--migrate-only'
|
||||
)
|
||||
& docker @migrateArgs
|
||||
if ($LASTEXITCODE -ne 0) { throw '数据库迁移失败。' }
|
||||
|
||||
$runArgs = @(
|
||||
'run', '--detach'
|
||||
'--name', 'jiaowu'
|
||||
'--restart', 'unless-stopped'
|
||||
'--env-file', '.env.docker'
|
||||
'--publish', '8080:8080'
|
||||
'--mount', 'type=bind,source=C:\certs\mysql-ca.pem,target=/run/secrets/mysql-ca.pem,readonly'
|
||||
$image
|
||||
)
|
||||
& docker @runArgs
|
||||
if ($LASTEXITCODE -ne 0) { throw '容器启动失败。' }
|
||||
```
|
||||
|
||||
Docker 镜像不包含 `.env`、数据库密码或 JWT 密钥。容器以非 root 用户运行，监听
|
||||
8080 端口；生产环境仍应由反向代理负责 HTTPS、访问日志和请求大小限制。
|
||||
|
||||
## 验证
|
||||
|
||||
```powershell
|
||||
|
||||
Reference in New Issue
Block a user