Clone
This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
配置参考
应用从进程环境变量和仓库根目录 .env 读取配置。进程环境变量优先：如果同名变量已经由操作系统、容器或部署平台注入，.env 不会覆盖它。
1. 配置文件
本地开发：
Copy-Item -LiteralPath .\.env.example -Destination .\.env
Docker Compose：
Copy-Item -LiteralPath .\.env.docker.example -Destination .\.env.docker
.env 支持：
- 空行；
#注释；KEY=value；- 可选
export KEY=value； - 单引号或双引号包裹的完整值。
修改 .env 后需要重启应用。
2. 基础运行配置
| 变量 | 默认/示例 | 说明 |
|---|---|---|
ASPNETCORE_ENVIRONMENT |
本地 Development |
Production 会启用生产密钥和数据库要求 |
ASPNETCORE_URLS |
http://127.0.0.1:4173 |
Kestrel 监听地址 |
DATABASE_CLIENT |
开发 sqlite，生产 mysql |
仅支持 sqlite、mysql |
如果直接设置 ASPNETCORE_ENVIRONMENT=Production 而没有配置 MySQL 和两个生产密钥，应用会拒绝启动，这是预期的安全行为。
3. SQLite
| 变量 | 默认值 | 说明 |
|---|---|---|
SQLITE_PATH |
./data/exam.sqlite |
相对路径按应用根目录解析，也可使用绝对路径 |
示例：
$env:DATABASE_CLIENT = 'sqlite'
$env:SQLITE_PATH = './data/exam.sqlite'
dotnet run --project .\src\Eis.Web\Eis.Web.csproj
4. MySQL 8.4
可以使用分项变量：
| 变量 | 必填 | 默认值 | 说明 |
|---|---|---|---|
MYSQL_HOST |
是 | 无 | MySQL 主机 |
MYSQL_PORT |
否 | 3306 |
端口 |
MYSQL_USER |
是 | 无 | 应用账号 |
MYSQL_PASSWORD |
视账号而定 | 空 | 密码 |
MYSQL_DATABASE |
是 | 无 | 数据库名 |
MYSQL_CONNECTION_LIMIT |
否 | 10 |
连接池最大连接数 |
也可以只设置：
| 变量 | 示例 |
|---|---|
DATABASE_URL |
mysql://exam_app:password@127.0.0.1:3306/exam_information |
DATABASE_URL 优先于全部 MYSQL_* 连接项。用户名和密码含特殊字符时必须按 URL 规则编码。
连接默认：
- 字符集
utf8mb4； - 连接超时 10 秒；
- 命令超时 30 秒；
- 启用连接池和连接重置。
5. 初始管理员
这些变量只在创建空数据库的初始管理员时使用：
| 变量 | 本地模板 | 说明 |
|---|---|---|
INITIAL_ADMIN_USERNAME |
admin |
初始超级管理员账号 |
INITIAL_ADMIN_PASSWORD |
Admin123! |
初始密码，生产必须更换 |
INITIAL_ADMIN_DISPLAY_NAME |
系统管理员 |
显示名 |
修改这些变量不会自动修改已经存在的管理员。已有账号应通过系统的密码修改或管理员重置功能维护。
6. TOTP 与文书防伪
| 变量 | 生产要求 | 说明 |
|---|---|---|
TOTP_ENCRYPTION_KEY |
至少 32 个字符 | 加密 TOTP 密钥并保护恢复码哈希 |
DOCUMENT_VERIFICATION_SECRET |
至少 32 个字符 | 对成绩单和录取通知书防伪载荷签名 |
要求：
- 两个值相互独立；
- 不与数据库密码、Cookie 或其他系统密钥共用；
- 由秘密管理平台或部署平台注入；
- 部署后稳定保存；
- 不提交到 Git。
影响：
- 更换
TOTP_ENCRYPTION_KEY：已绑定 TOTP 可能无法解密。 - 更换
DOCUMENT_VERIFICATION_SECRET：历史文书查询码会失效。
开发环境未配置时使用仅供开发的稳定派生值。DOCUMENT_VERIFICATION_SECRET 未设置时还兼容读取 SESSION_SECRET，但新部署应使用独立变量，不依赖兼容路径。
7. Redis 普通缓存
| 变量 | 默认值 | 说明 |
|---|---|---|
REDIS_URL |
未配置 | redis:// 或 rediss:// 地址，可在路径指定逻辑 DB |
REDIS_CACHE_PREFIX |
exam-information |
缓存 key 前缀 |
REDIS_CACHE_TTL_SECONDS |
60 |
公开数据缓存秒数，最大 86400 |
REDIS_RESULTS_CACHE_TTL_SECONDS |
86400 |
已发布成绩缓存秒数 |
REDIS_CONNECT_TIMEOUT_MS |
1500 |
Redis 连接超时，最大 30000 |
LOCAL_CACHE_MAX_ENTRIES |
200 |
本机回退缓存上限，最大 5000 |
普通缓存 Redis 暂时不可用时，应用回退到本机缓存，并保持写后失效语义。
8. Redis 认证状态
| 变量 | 默认值 | 说明 |
|---|---|---|
REDIS_SESSION_URL |
复用 REDIS_URL 端点 |
可指定独立 Redis |
REDIS_SESSION_DB |
缓存 DB 为 0 时自动选 1，否则选 0 | 认证状态逻辑 DB |
REDIS_SESSION_PREFIX |
exam-information:auth |
Session 和临时状态 key 前缀 |
AUTH_SESSION_TTL_SECONDS |
28800 |
登录 Session，默认 8 小时，最大 30 天 |
AUTH_LOGIN_CHALLENGE_TTL_SECONDS |
300 |
TOTP 登录挑战，最大 1 小时 |
AUTH_TOTP_SETUP_TTL_SECONDS |
600 |
TOTP 绑定临时状态，最大 1 小时 |
普通缓存和认证状态不得使用同一 Redis 端点的同一逻辑 DB。错误配置时应用拒绝启动。
示例：
REDIS_URL=redis://127.0.0.1:6379/0
REDIS_SESSION_DB=1
独立实例：
REDIS_URL=rediss://cache.example.com:6379/0
REDIS_SESSION_URL=rediss://session.example.com:6379/0
Redis Cluster 通常不支持非 0 逻辑 DB，此时应使用 REDIS_SESSION_URL 指向独立端点或实例。
9. 数据状态快照
| 变量 | 默认值 | 说明 |
|---|---|---|
DATABASE_STATE_CACHE_TTL_MS |
30000 |
MySQL 外部直写后，全量只读快照最长复用毫秒数 |
应用内写入会立即失效；SQLite 还会通过 PRAGMA data_version 识别外部连接提交。
10. 公开站点信息
| 变量 | 用途 |
|---|---|
PUBLIC_SITE_NAME |
机构名称 |
PUBLIC_SITE_CODE |
机构代码 |
PUBLIC_SITE_PHONE |
联系电话 |
PUBLIC_SITE_ADDRESS |
地址 |
PUBLIC_SITE_EMAIL |
邮箱 |
PUBLIC_SITE_HERO_EYEBROW |
首页英文眉题 |
PUBLIC_SITE_HERO_TITLE |
首页主标题前半段 |
PUBLIC_SITE_HERO_HIGHLIGHT |
首页主标题强调段 |
PUBLIC_SITE_HERO_DESCRIPTION |
首页说明 |
PUBLIC_SITE_FOOTER_NOTICE |
页脚提示 |
这些变量会覆盖数据库中的演示机构展示信息，只通过公开首页接口返回非敏感字段。
11. 兼容迁移开关
源码仍可读取 AUTH_NATIVE_ENABLED、CANDIDATE_NATIVE_ENABLED 和若干 ADMIN_NATIVE_* 变量，但当前 appsettings.json 已默认启用全部 ASP.NET Core 原生域，旧 Node.js API 已移除。
正常部署不需要设置这些变量。除非正在调试迁移兼容行为，不应把它们加入新环境模板。
12. 生产配置示例
以下只展示结构，密钥和密码必须替换：
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://0.0.0.0:4173
DATABASE_CLIENT=mysql
MYSQL_HOST=mysql.internal
MYSQL_PORT=3306
MYSQL_USER=exam_app
MYSQL_PASSWORD=replace-me
MYSQL_DATABASE=exam_information
MYSQL_CONNECTION_LIMIT=20
REDIS_URL=rediss://cache.internal:6379/0
REDIS_SESSION_URL=rediss://session.internal:6379/0
REDIS_CACHE_PREFIX=exam-information
REDIS_SESSION_PREFIX=exam-information:auth
TOTP_ENCRYPTION_KEY=replace-with-a-unique-secret-at-least-32-characters
DOCUMENT_VERIFICATION_SECRET=replace-with-another-unique-secret-at-least-32-characters
INITIAL_ADMIN_USERNAME=admin
INITIAL_ADMIN_PASSWORD=replace-with-a-strong-initial-password
INITIAL_ADMIN_DISPLAY_NAME=系统管理员
13. 上线检查
ASPNETCORE_ENVIRONMENT=Production。- 数据库目标明确，不是测试库或旧 SQLite 文件。
- 两项 32 字符以上的独立密钥已由秘密管理注入。
- 初始管理员密码已更换。
- Redis 缓存与认证状态未使用同一逻辑 DB。
- 多实例已使用共享认证 Redis。
.env、.env.docker未提交到版本库。- 公开机构信息已改成真实信息。
/health/live和/health/migration可由运维系统检查。