unis-oa/backend/config.prod.toml.example

205 lines
16 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# =============================================================================
# UnisOA 后端配置文件 —— 生产档模板(复制成 config.prod.toml 再填)
# -----------------------------------------------------------------------------
# 部署机上:
# cd backend
# cp config.prod.toml.example config.prod.toml && vi config.prod.toml
# OA_ENV=prod ./scripts/prod-api.sh # 或 systemd / docker 里给 OA_ENV=prod
#
# 读法:先读同目录的 config.toml(各环境公共的基础值),再用本文件逐段盖上来。
# 本文件只写跟公共值不一样的键,没写的沿用 config.toml;跟本地测试那一份
# (config.dev.toml)互不影响 —— 本机不设 OA_ENV 时读的是 dev 档,根本看不到这里。
#
# 取值优先级(高的赢):
# 环境变量 OA_* > 数据库(界面上保存过的) > 本文件 > config.toml > 内置默认值
# 容器 / K8s 部署更省事的做法是密钥一个都不写文件,全用环境变量注入:
# 下面每一项后面都注了变量名;配置文件这时只当兜底。
#
# 本文件带真实口令与密钥,**不要提交到仓库**(只在部署机上,或者挂成 secret 卷)。
# 生产档启动时后端会做一轮上线体检:默认/占位的 JWT 密钥、没关的演示数据、
# 空的 MySQL 口令、还是 admin123 的超管口令,都会在日志里点名。
# =============================================================================
# -----------------------------------------------------------------------------
# 【引导配置】生产 MySQL:改完必须重启(连不上库就没地方读配置了)
# -----------------------------------------------------------------------------
[database]
host = "" # 生产库地址(OA_DB_HOST)
port = 3306 # 端口(OA_DB_PORT)
user = "oa" # 建议用只建好本库权限的专用账号,别用 root(OA_DB_USER)
password = "" # 口令(OA_DB_PASSWORD);容器里用 -e / secret 注入
name = "unis_oa" # 库名(OA_DB_NAME)
# 生产库通常交给 DBA:关掉自动建表补列,用 sql/schema.sql 手工建、按升级脚本改
auto_create_schema = false
# 允许后端新建的库名(OA_DB_CREATE_ALLOWLIST):改成生产库的名字,一个环境一个库。
# 关掉自动建表之后这道闸更要紧——库名被注错时后端报错退出,不会在生产 MySQL 上建个空库
create_allowlist = "unis_oa"
# -----------------------------------------------------------------------------
# 【引导配置】登录令牌签名:改了要重启,且已登录的会话会全部失效
# 这一项绝不能留占位值,后端启动体检会点名。生成一个:
# python3 -c "import secrets;print(secrets.token_urlsafe(48))"
# -----------------------------------------------------------------------------
[security]
jwt_secret = "" # 签名密钥(OA_JWT_SECRET),每个环境一个,别复用
# 空闲多久要求重新登录(分钟)(OA_SESSION_IDLE_MINUTES)。0 = 不启用。
# 对接统一身份后建议开着:Hub 那边登出不会回收本系统已建立的会话(对接指南第 8 节)。
# 开了之后访问令牌有效期会被压到不超过这个窗口。
session_idle_minutes = 480
# -----------------------------------------------------------------------------
# 【引导配置】服务监听:改完要重启。前面有 nginx 时监听 127.0.0.1 更安全
# -----------------------------------------------------------------------------
[server]
host = "0.0.0.0" # 监听地址(OA_HOST)
port = 8000 # 监听端口(OA_PORT)
# HTTP 进程数(OA_WORKERS)。**默认 1,不写这行就是现在这样**:一个进程、一条后台任务线程。
# 加进程买的是 CPU:组织树、待办列表这类返回体不小的只读接口,实测 1 进程 72 次/秒 →
# 4 进程 196~214 次/秒(p50 105ms → ~30ms);发起与审批这类写路径瓶颈在库往返与 fsync,
# 加进程不涨(两轮实测:1 进程 16.3/25.3 单/秒,4 进程 18.0/21.3 单/秒,互相穿过)。
# 开之前算连接账:进程数 ×(pool_size 16 + max_overflow 32)别大过 MySQL 的 max_connections,
# 超了不是变慢是在池子里排队(默认最多等 30 秒);启动时自己会算并喊出来。
# 后台任务不受这个数影响,永远只有一个进程在跑(抢 oa_worker_lease 租约),见 docs/multi-worker-deployment.md。
# workers = 4
# 跨域来源是运行配置(存库、界面上改完即生效,不用重启)。前端与后端同源部署
# (后端直接托管 frontend/dist)时留空即可;真要跨域就写全 https 的域名,别写 *。
# cors_origins = ["https://oa.example.edu.cn"]
# -----------------------------------------------------------------------------
# 【引导配置】首次启动种的数据:生产只种必要的内置超管,不种演示数据
# 本地管理员的账号与口令都在数据库里(system.admin_account 记账号名,
# users.password_hash 记口令,config:hub.hub_local_accounts 记谁能走本地口令)。
# admin_account 填 localadmin 是"改名开关":本部署把 admin 这个名字让给了统一身份
# 同步进来的人(见 docs/hub-integration.md 5.1),本地内置号改名当应急账号。
# 不想让名就删掉这一行,内置号用库里现有的名字。
# -----------------------------------------------------------------------------
[seed]
admin_account = "localadmin" # 内置超管账号名(OA_ADMIN_ACCOUNT)
admin_password = "" # 初始口令(OA_ADMIN_PASSWORD),生产务必给一个;留空等于没有口令,体检会点名
demo_data = false # 演示数据(OA_SEED_DEMO),生产关
# -----------------------------------------------------------------------------
# 【统一身份(Hub)】系统设置页 →「统一身份登录」,保存即生效
# 对接口径与每一项的含义见 docs/hub-integration.md;这里只列生产必填的
# -----------------------------------------------------------------------------
[hub]
enabled = true # 总闸(OA_HUB_ENABLED):生产走统一身份登录
base_url = "" # Hub 站点地址(OA_HUB_BASE_URL),不带结尾斜杠
directory_key = "" # 目录密钥(OA_HUB_DIRECTORY_KEY),找 Hub 管理员领
login_mode = "hybrid" # hub 只认 Hub / hybrid Hub 优先、挂了回退本地(OA_HUB_LOGIN_MODE)
# 只允许统一门户免登就写 sso:本系统不再收账号密码,登录页只留「前往统一门户」,
# 账号密码那一栏彻底没了(应急账号照旧走本地口令)。改这一项之前先把下面三项配齐
# 并测过一轮免登,否则谁都进不来
# 应急通道出厂值(OA_HUB_LOCAL_ACCOUNTS):这些账号只用本地口令,出事时靠它们进门。
# 生效的名单在数据库 config:hub 里,启动时按内置超管的账号名种下、改名时跟着搬,
# 生产只留内置超管一个,测试那串演示演员名单别带上来;这一行只在库里那一行被
# 恢复成默认之后兜底,写就写内置超管现在这个账号名,别留旧名字。
local_accounts = "localadmin"
disabled = false # 应急总闸(OA_HUB_DISABLED):也能在「系统设置 → 统一身份应急总闸」上切
# --- 统一门户免登(对接指南第 3、4 节):三项配齐才生效,缺一项状态接口会点名 ---
app_code = "" # 本系统的应用编码(OA_HUB_APP_CODE),Hub 注册应用时给的 code
integration_key = "" # 免登应用密钥(OA_HUB_INTEGRATION_KEY),只在注册/轮换那一次回显
# 配套要在 Hub 上把本系统的落地地址登记好(这一步在 Hub 后台做,不在本文件里):
# launch_url https://<本系统对外地址>/api/v1/auth/sso/callback
# (想用短地址就填别名 /sso/hub;只想让票据走前端落地页就填 /sso)
# redirect_uris 同上那条完整地址,Hub 按整串精确匹配,scheme/端口/路径逐字符都要对上
# 可访问角色 至少勾一个,一个都不勾时门户里谁也看不到这张卡片(管理员也不豁免)
# 起来之后 GET /api/v1/hub/status 的 sso.callback_url / alias_url 会把完整地址回显出来,
# 系统设置页「统一身份」状态卡悬停也看得到,照抄给 Hub 管理员即可。
# portal_url = "" # 统一门户首页(OA_HUB_PORTAL_URL),留空用上面的 base_url
# [hub.sso]
# enabled = true # 允许免登(OA_HUB_SSO_ENABLED)
# state_required = false # 只认从本系统发起的免登(OA_HUB_SSO_STATE_REQUIRED)
# -----------------------------------------------------------------------------
# 【统一身份权限】默认关闭:权限与数据范围完全按本系统的角色矩阵走。
# 要对账就先开 shadow(只显示 Hub 的口径、不改判定),用页面上的代查看清楚了
# 再切 enforce;口径见 docs/hub-integration.md §9。接口复用上面 [hub] 那套凭证
# -----------------------------------------------------------------------------
# [hub.perm]
# enabled = false # 启用统一身份权限(OA_HUB_PERM_ENABLED)
# mode = "shadow" # shadow 只对照 / enforce 以统一身份为准(OA_HUB_PERM_MODE)
# application_id = "" # 问哪个应用的权限(OA_HUB_PERM_APPLICATION_ID),留空用上面的 app_code
# admin_query = true # 免登用户手上没有 Hub 令牌时由服务端代查(OA_HUB_PERM_ADMIN_QUERY)
# keep_local = true # Hub 没给出可识别权限码时保留本地权限,别一处没配好就锁死所有人
# -----------------------------------------------------------------------------
# 【文件存放位置】系统设置页 →「文件存放位置」,保存即生效
# 上传附件与信息资讯进 MinIO,网盘文件落本地磁盘(库里只存 uri,换存储不用洗库)
# -----------------------------------------------------------------------------
[storage.minio]
endpoint = "" # 只写 主机:端口,不带 http://(OA_MINIO_ENDPOINT)
access_key = "" # Access Key(OA_MINIO_ACCESS_KEY)
secret_key = "" # Secret Key(OA_MINIO_SECRET_KEY),接口永不回显
bucket = "unis-oa" # 桶名(OA_MINIO_BUCKET),后端不建桶,先建好设 private
upload_path = "" # 对象键前缀(OA_MINIO_UPLOAD_PATH),留空 = 桶根
# secure = true # 地址是 HTTPS 域名(不带端口)时打开(OA_MINIO_SECURE);
# 9000 这类 S3 API 端口保持 false
# MinIO 连不上时要不要退回本地磁盘(OA_STORAGE_FALLBACK,默认 true)。生产建议保持
# true 保可用性;不想让附件落到容器里就改 false,宁可报上传失败。
# [storage]
# fallback_to_local = true
# -----------------------------------------------------------------------------
# 【共享缓存与限流】Redis:可选件,**地址留空 = 整套不启用**
# 单副本部署可以一直空着;多副本(uvicorn --workers N 或两台机器)建议填上——
# 外部取数结果 / Hub 服务令牌 / Hub 权限 / 字典选项各副本共用一份,开放接口与外部
# 数据源的每分钟限额不再被副本数放大,界面上改了配置其它副本当场跟上。
# 连不上或超时自动退回老口径(各进程自己缓存、限流查库、失效最多等 2 秒),不影响业务。
# 填完看 GET /api/v1/system/redis 的 active;界面上改保存即生效,不用重启
# -----------------------------------------------------------------------------
[redis]
enabled = true # 总闸(OA_REDIS_ENABLED)
url = "" # 连接串(OA_REDIS_URL),填了就忽略下面几项;如 redis://:口令@10.0.0.9:6379/0
host = "" # 地址(OA_REDIS_HOST),不带 redis:// 与端口;留空 = 不启用
port = 6379 # 端口(OA_REDIS_PORT)
db = 0 # 库号(OA_REDIS_DB),0-15
username = "" # ACL 用户名(OA_REDIS_USERNAME);只有 requirepass 时留空
password = "" # 口令(OA_REDIS_PASSWORD),也可以走环境变量注入,接口永不回显
key_prefix = "unisoa-prod" # 键前缀(OA_REDIS_KEY_PREFIX),多个环境共用一台时务必分开
socket_timeout_seconds = 2 # 读写超时(OA_REDIS_TIMEOUT)
max_connections = 32 # 每进程连接池上限(OA_REDIS_MAX_CONNECTIONS)
rate_limit_enabled = true # 限流计数走 Redis(OA_REDIS_RATE_LIMIT)
broadcast_enabled = true # 失效广播走 Redis(OA_REDIS_BROADCAST)
dict_cache_seconds = 60 # 字典选项共享秒数(OA_REDIS_DICT_CACHE),0 = 每次现查库
# -----------------------------------------------------------------------------
# 【组织人员同步】生产按业务低峰跑;其余同步开关在系统设置页改,保存即生效
# -----------------------------------------------------------------------------
[hub.sync]
time = "02:00" # 每天本地时间 HH:MM 跑一趟(OA_HUB_SYNC_TIME)
# 增量同步(变更流水轮询)默认就开着,每 45 秒一趟;生产要调周期或单批条数就放开这几行
# [hub.sync.changes]
# interval_seconds = 45 # 轮询周期(OA_HUB_SYNC_CHANGES_INTERVAL_SECONDS)
# limit = 200 # 单批条数(OA_HUB_SYNC_CHANGES_LIMIT),Hub 上限 500
# full_on_gap = true # 落后过多就回全量(OA_HUB_SYNC_CHANGES_FULL_ON_GAP)
# -----------------------------------------------------------------------------
# 【表单嵌外部页面】表单上那一格开别的业务系统的页面,地址与密钥在「外部数据源」页
# 登记,这里只有部署闸门;改完重启。设计见 docs/embed-page-field-design.md
# -----------------------------------------------------------------------------
[embed]
enabled = true # 总闸(OA_EMBED_ENABLED)
csp = true # 下发 frame-src / frame-ancestors(OA_EMBED_CSP),排查预览问题时先关这个
# frame_extra = [] # 注册表之外再允许的来源(OA_EMBED_FRAME_EXTRA),一般不用填
# ticket_ttl = 60 # 免登短码存活秒数(OA_EMBED_TICKET_TTL),对方服务端要在这之内来验票
# -----------------------------------------------------------------------------
# 部署清单(少一样都会在日志里看到对应的提示)
# 1. OA_ENV=prod,或者干脆只给 OA_CONFIG=/etc/unisoa/config.prod.toml(只读那一个文件)
# 2. [database] 四项填好,库和账号先建好(auto_create_schema=false 时表也得手工建)
# 3. [security] jwt_secret 换成随机值
# 4. [seed] demo_data=false、admin_password 给一个
# 5. [hub] base_url / directory_key 填好,enabled=true;要免登再补 app_code 与
# integration_key,并把本系统的回调地址(/api/v1/auth/sso/callback 或别名
# /sso/hub)连同可访问角色一起让 Hub 登记好,缺一样免登就是进不来;
# 要彻底不收本地密码再把 login_mode 改成 sso;
# 权限要向 Hub 要口径再开 [hub.perm](先 shadow 对账,再 enforce)
# 6. [storage.minio] 四项填好,桶先建好
# 7. 前端 pnpm build 后由后端托管 frontend/dist,同源部署不用配跨域
# 8. 多副本部署再填 [redis](单副本留空即可):填完看
# GET /api/v1/system/redis 的 active 是不是 true
# =============================================================================
# =============================================================================