.env
环境变量和密钥，随部署环境配置，不纳入版本库
在阅读完 配置说明 后，我们已经了解 .env 与 site.config.ts 的分工。本节将逐项介绍 .env 中的配置项。开发环境与生产环境共用同一模板 .env.example，复制为 .env 后按需启用。
必填项
数据库连接与运行模式必须配置：
| 变量 | 默认 | 说明 |
|---|---|---|
DB_HOST | localhost | PostgreSQL 地址；Docker compose 内强制覆盖为 postgres |
DB_PORT | 5432 | PostgreSQL 端口 |
DB_USER | postgres | PG 用户；compose 默认是 imqi1 |
DB_PASSWORD | — | PG 密码，无默认，留空启动失败 |
DB_NAME | — | PG 数据库名；Docker compose 用它建库，缺省 imqi1-cms |
NODE_ENV | development | 生产环境设为 production，Nuxt 的构建与 SSR 路径都按它分流 |
注：NODE_ENV 在开发环境不需要设置。在构建时，Nuxt 内部会自动将这个值设为 production。唯一需要显式设置的是生产环境。
应用密钥
三项密钥都只供服务端使用，不会下发到浏览器：
| 变量 | 默认 | 说明 |
|---|---|---|
SSR_INTERNAL_REQUEST_SECRET | 启动时随机生成 | SSR 内部请求绕过 referer 门禁的密钥；空值启动时随机生成、重启即变，强烈建议在生产环境配置 |
LOGIN_SECRET | SSR_INTERNAL_REQUEST_SECRET | 2FA 验证与「信任此设备」令牌的 HMAC 签名密钥；空值时降级到 SSR_INTERNAL_REQUEST_SECRET，再空才随机生成，强烈建议在生产环境配置一个和 SSR_INTERNAL_REQUEST_SECRET 不一致的值 |
MINI_API_SECRET | — | 小程序 /api/mini/* HMAC 签名密钥；生产空值则小程序接口全部 401，开发环境跳过校验；需与小程序端 VITE_MINI_API_SECRET 完全一致 |
受信代理
应用侧与 nginx 侧各有一个名字相近的变量，作用域不同，两侧都要配置才完整：
| 变量 | 默认 | 说明 |
|---|---|---|
TRUSTED_PROXY | 仅本机回环地址 | 应用侧白名单，逗号分隔，可填单个地址或网段。决定应用是否采信反向代理转来的客户端地址：代理不在本机时必须填回源地址，否则评论来源与登录限流会退化成同一个地址 |
DEPLOY_TRUSTED_PROXY | 不启用 | nginx 侧白名单，决定从哪些来源恢复真实客户端地址；留空则不恢复 |
请求经过反向代理后，应用在连接上看到的对端是代理自己的地址，真实客户端地址只能由代理写进请求头转交。而请求头是普通文本、客户端自己就能伪造，所以应用默认不采信，只认来自已知代理的对端。转发链上每一跳都会往头里追加自己看到的对端，应用因此只取最后一段，它由最近的可信代理写入，客户端伪造不了。
微信小程序
| 变量 | 默认 | 说明 |
|---|---|---|
WECHAT_MINI_APPID | — | 微信小程序 AppID；与 WECHAT_MINI_SECRET 配对才有意义，缺则小程序码入口隐藏 |
WECHAT_MINI_SECRET | — | 微信小程序 AppSecret |
小程序接口签名密钥见 应用密钥 一节的 MINI_API_SECRET，主站与小程序必须使用同一值。
高德地图
| 变量 | 默认 | 说明 |
|---|---|---|
AMAP_KEY | — | 高德 JS API Key；旅行足迹地图功能依赖，缺则该功能不可用 |
AMAP_SECURITY_CODE | — | 高德 JS API 安全密钥；与 Key 配对才有意义 |
上传目录
| 变量 | 默认 | 说明 |
|---|---|---|
UPLOADS_DIR | <public>/uploads | 本地上传根目录；相对路径按进程 cwd 解析，绝对路径直接用；Docker compose 里同时作为 bind mount 宿主路径 |
日志目录
| 变量 | 默认 | 说明 |
|---|---|---|
LOGS_DIR | ./logs/ | 站点日志（9 类分类）根目录，优先于 site.config.ts 的 logs.dir；相对路径按进程 cwd 解析；Docker compose 里同时作为 bind mount 宿主路径，格式与分类含义见 日志系统 |
部署脚本
仅供 bun run <script> 工具使用，应用进程不会读取：
| 变量 | 默认 | 说明 |
|---|---|---|
DEPLOY_PORT | — | bun run nginx:generate 反代上游端口；Docker compose 模板默认 3000 |
DEPLOY_PROJECT_ROOT_DIR | — | bun run nginx:generate 写入 nginx 片段内 /sw.js /robots.txt 的静态文件根目录 |
DEPLOY_SITE_DOMAIN | — | bun run nginx:generate 主站域名，打印用 |
DEPLOY_CDN_DOMAIN | — | bun run nginx:generate CDN 域名，nginx 用它做 /favicon.ico /manifest.webmanifest 301 重定向 |
DEPLOY_ENABLE_CDN_REDIRECT | — | bun run nginx:generate 是否输出上述 CDN 301 重定向片段，取值字符串 "true" 才输出；未设置时脚本直接退出 |
DEPLOY_TRUSTED_PROXY | — | bun run nginx:generate 写入 nginx 侧 set_real_ip_from 的回源地址段（逗号分隔，可填单个地址或网段） |
DEPLOY_REAL_IP_HEADER | X-Forwarded-For | bun run nginx:generate 真实客户端 IP 在哪个转发头 |
COS_SECRET_ID | — | bun run upload:cos 腾讯云 COS SecretId |
COS_SECRET_KEY | — | bun run upload:cos 腾讯云 COS SecretKey |
COS_BUCKET | — | bun run upload:cos COS 桶名 |
COS_REGION | — | bun run upload:cos COS 地域 |
COS_CONCURRENCY | 15 | bun run upload:cos 上传并发数 |
SERVER_HOST | — | bun run upload:server 上传目标服务器 IP |
SERVER_PORT | 22 | bun run upload:server SSH 端口 |
SERVER_USER | root | bun run upload:server SSH 用户 |
SERVER_PASSWORD | — | bun run upload:server SSH 密码 |
SERVER_UPLOAD_DIR | — | bun run upload:server 远端上传目录 |
SERVER_UPLOAD_CONCURRENCY | 8 | bun run upload:server 上传并发数 |
BT_PANEL_URL | — | bun run restart:server / bun run clear:redis 宝塔面板地址 |
BT_API_KEY | — | 同上，宝塔接口密钥 |
BT_PROJECT_NAME | — | 同上，宝塔 Node 项目管理器里的项目名 |
FFMPEG_PATH | — | bun run compress:livephoto ffmpeg 可执行路径，空则依次试 ffmpeg-static → 系统 PATH |
其中 bun run clear:redis 清空的是该 Redis 实例的全部 16 个库（0–15），不只是本站的缓存，同实例上别的库会一起被清掉。
MCP 运维令牌
| 变量 | 默认 | 说明 |
|---|---|---|
MCP_OPS_TOKEN | 空 | /mcp 端点运维工具组的门禁令牌，建议随机长字符串；留空则五个运维工具完全不注册（fail-closed） |
配置后 MCP Server 会额外注册系统状态、日志、内容统计、缓存诊断与清缓存五个运维工具，调用时必须携带本令牌作为 token 入参；令牌每请求现读，生产补配无须重新构建。
小程序的环境变量
小程序是独立子包，拥有自己的 mini/.env.development 与 mini/.env.production，不使用主站 .env。小程序端的 VITE_API_BASE_URL 与 VITE_MINI_API_SECRET 见 小程序。