unis-oa/backend/config.toml.example

585 lines
40 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.toml 各环境公共的基础值(仓库里有,只写跟默认值不一样的项)
# config.dev.toml 测试档:本机 python run.py 读的就是它(不设 OA_ENV 时默认)
# config.prod.toml 生产档:部署机上 cp config.prod.toml.example config.prod.toml
#
# 每一档读两份:先 config.toml,再叠 config.<环境名>.toml(深合并,只覆盖写到的键)。
# 所以"本机起来就是测试配置、线上 OA_ENV=prod 起来就是生产配置",见 README「多套环境」。
# -----------------------------------------------------------------------------
# **运行配置存在数据库里,不在这里改**:登录系统 → 系统设置页 → 保存即生效,
# 不用重启服务。配置住在 MySQL 的 oa_system_setting 表里,一个配置组一行:
# config:site / config:security / config:hub / config:hub_sync /
# config:ai / config:storage / config:server
#
# 那这个文件还剩什么用?两件事:
#
# 1. 引导配置:连上数据库之前就必须知道的东西,只有这里能写,改完要重启 ——
# [database] MySQL 地址与账号、[server] 监听端口、[security] 的 JWT 签名密钥、
# [seed] 内置超管的初始口令。
# 2. 运行配置的出厂值:库里还没有某一项时,每次取值现读本文件(改了本文件重启
# 即生效)。**本文件的值不会被写进数据库**:只有在系统设置页点过保存的那一项
# 才会进库,从那一刻起那一项以库为准,本文件再改也不影响它。
# 界面上每一项都写明当前值是谁给的(配置文件 / 数据库 / 环境变量),
# 点「恢复默认」= 把库里那一行删掉,回到读本文件。
#
# 取值优先级(高的赢):
# 环境变量 OA_* > 数据库 oa_system_setting > config.<环境名>.toml > config.toml > 代码默认值
# 每一项对应的环境变量名写在条目后面;环境变量一旦设置就会盖住库里的值,
# 系统设置页会把这些项标成"被环境变量固定",容器 / CI 注入密钥就靠它。
#
# 查找顺序:设了 OA_CONFIG 就只读那一个文件;否则读 OA_CONFIG_DIR(默认 backend/)下的
# config.toml + config.<OA_ENV>.toml(OA_ENV 没设就是 config.dev.toml)。
# 带真实口令与密钥的分档文件(config.dev.toml / config.prod.toml)别提交到公共仓库。
#
# 下面从 [site] 开始的各段都是运行配置的出厂值。想让本文件的修改生效,二选一:
# · 在系统设置页里改(推荐:进库、立即生效、不用重启);
# · 改本文件然后重启后端 —— 但前提是这个配置项从没在界面上保存过
# (系统设置页里 "来源" 显示"配置文件" 的项才是这种情况)。
# =============================================================================
# -----------------------------------------------------------------------------
# 【引导配置】MySQL 连接:改完必须重启(连不上库就没地方读配置了)
# 库不存在时后端会自己 CREATE DATABASE(见 auto_create_schema 与 ensure_database)
# -----------------------------------------------------------------------------
[database]
# 数据库地址(OA_DB_HOST)
host = "127.0.0.1"
# 端口(OA_DB_PORT)
port = 3306
# 账号(OA_DB_USER)
user = "root"
# 口令(OA_DB_PASSWORD)
password = ""
# 库名(OA_DB_NAME)
name = "unis_oa"
# 启动时自动建表 / 补新列 / 补索引(OA_AUTO_CREATE_SCHEMA)。
# 生产库交给 DBA 管的时候可以关掉,改用 sql/schema.sql 手工建。
auto_create_schema = true
# 启动时读表结构的方式(OA_DB_SCHEMA_REFLECTION):bulk = 三条 information_schema 查询
# 一次把全库的表名/列名/索引名读齐(默认);per_table = 一张表一次 SHOW CREATE TABLE。
# 建表补列那五步只需要这三样信息,逐表反射在远端库上是 60 个来回、实测 1.7 秒,一次读齐
# 实测 0.45 秒。留 per_table 是给"information_schema 被代理挡得不全"那种环境当退路:
# 功能一模一样,只是启动慢回去。填错按 bulk 走并喊一声。
schema_reflection = "bulk"
# 允许后端新建的库名,逗号分隔,结尾 * 是前缀通配,* = 不设限(OA_DB_CREATE_ALLOWLIST)。
# 只管"目标库不存在、要新建"这一种情况:库在就照常连。默认只有上面 name 那一个名字,
# 一个环境一个库——库名写错时后端报错退出,而不是在 MySQL 上凭空多出一个没人认领的库。
create_allowlist = "unis_oa"
# -----------------------------------------------------------------------------
# 【引导配置】登录令牌签名:jwt_secret / jwt_algorithm 改了要重启
# (令牌有效期 access_token_minutes / refresh_token_days 是运行配置,
# 在系统设置页改,保存即对新建的令牌生效)
# -----------------------------------------------------------------------------
[security]
# 本地 JWT 的签名密钥(OA_JWT_SECRET)。生产环境务必换掉:
# 换掉之后所有已登录的会话立即失效,用户要重新登录
jwt_secret = ""
# 签名算法(OA_JWT_ALGORITHM),一般是 HS256
jwt_algorithm = "HS256"
# 访问令牌有效期(分钟)(OA_ACCESS_TOKEN_MINUTES),720 = 12 小时
access_token_minutes = 720
# 刷新令牌有效期(天)(OA_REFRESH_TOKEN_DAYS)
refresh_token_days = 30
# 空闲多久后要求重新登录(分钟)(OA_SESSION_IDLE_MINUTES)。0 = 不启用(老部署行为不变)。
# 对接统一门户后建议开:Hub 那边登出不会回收本系统已建立的会话(对接指南第 8 节),
# 这一段只能下游自己管。开了之后访问令牌有效期会被压到不超过这个窗口。
session_idle_minutes = 0
# -----------------------------------------------------------------------------
# 【引导配置】服务监听:改完要重启
# (允许跨域的前端来源 cors_origins 是运行配置,界面上改完立刻生效)
# -----------------------------------------------------------------------------
[server]
# 监听地址(OA_HOST),0.0.0.0 = 接受所有网卡的连接
host = "0.0.0.0"
# 监听端口(OA_PORT)。用 run.py 或 scripts/dev-api.sh 启动时读这里;
# 用 uvicorn 命令行启动时以命令行的 --port 为准。改完要重启。
port = 8000
# 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
# 这一项是运行配置(存在库里的 config:server),界面上「跨域与接口」改完立刻生效;
# 写在这里只是出厂模板。允许跨域调用接口的前端来源(OA_CORS_ORIGINS)。
# 前端和后端同源部署(后端直接托管 frontend/dist)时留空也行;
# 本机 127.0.0.1 与 localhost 的任意端口一律放行,开发时不用配。
cors_origins = ["http://localhost:3000", "http://127.0.0.1:3000"]
# -----------------------------------------------------------------------------
# 【出厂模板】站点信息:系统设置页 →「站点信息」,保存即生效
# -----------------------------------------------------------------------------
[site]
# 系统名称(OA_SITE_NAME)
name = "UnisOA 流程审批平台"
# Logo 路径(OA_SITE_LOGO),相对前端静态目录。默认那一枚就是浏览器页签上的图标,
# 与系统左上角那块 "OA" 磁贴同一张图(整套图标见 frontend/scripts/gen-icons.py)
logo = "/favicon.svg"
# 一句话描述(OA_SITE_DESCRIPTION),显示在登录页
description = "基于 Python 的 OA 流程审批系统"
# 允许在登录页注册新账号(OA_REGISTER_ENABLED)。统一身份开启后建议保持 false
register_enabled = false
# -----------------------------------------------------------------------------
# 【引导配置】首次启动种的数据:只在库里没有对应记录时生效,改这里不动已有数据
# -----------------------------------------------------------------------------
[seed]
# 内置超管账号(OA_ADMIN_ACCOUNT)。账号建好之后它的户口在数据库里
# (oa_system_setting 的 system.admin_account),这一行只是出厂值 + 改名开关:
# 写了新名字就当作"要把内置超管改成这个名字",没写就用库里现有的
admin_account = "admin"
# 内置超管初始口令(OA_ADMIN_PASSWORD)。首次登录后请立刻改密
admin_password = "admin123"
# 种演示数据:组织架构、两个示例流程、首页资讯/会议/日程示例内容
# (OA_SEED_DEMO)。演示数据会真的往 MinIO 传示例封面,共享存储不通时
# 一次启动能磨几分钟,建议生产关掉。
demo_data = true
# -----------------------------------------------------------------------------
# 【出厂模板】统一身份(Hub)登录:系统设置页 →「统一身份登录」,保存即生效
# 对接口径见 docs/hub-integration.md
# -----------------------------------------------------------------------------
[hub]
# 总闸(OA_HUB_ENABLED)。false = 纯本地账号登录,行为与没对接前完全一致
enabled = false
# Hub 站点地址(OA_HUB_BASE_URL),不带结尾斜杠;留空等于没开
base_url = ""
# 目录密钥(OA_HUB_DIRECTORY_KEY)——拉全量人员与组织全靠它,找 Hub 管理员领。
# 后端以请求头 X-Directory-Key 带出去:Hub 只认这个头,不带回 401 "token已失效",
# 密钥不对回 401 "集成密钥无效"。只填密钥那一串,别连头名和空格一起粘。
# 配上之后同步不必再登录换 token;界面上这一栏叫「目录密钥」,只回"配了没有"。
directory_key = ""
# 登录校验模式(OA_HUB_LOGIN_MODE):
# hub = 只认 Hub,本地口令不参与
# hybrid = Hub 优先,Hub 连不上/超时/5xx 时回退本地口令(Hub 明确说密码错不回退)
# sso = 只允许统一门户免登:本系统不再收账号密码,登录页只留「前往统一门户」
# local = 只用品口令,不查 Hub(只同步、不托管登录时用这个)
login_mode = "hybrid"
# 单次请求超时(秒)(OA_HUB_TIMEOUT_SECONDS)
timeout_seconds = 10
# 登录拿到 Hub token 之后再调一次 POST /api/v1/auth/token/verify 复核
# (OA_HUB_VERIFY_TOKEN)。打开后"登录接口放行但账号已被停用"这种账号进不来
verify_token = true
# Hub 认了这个账号但本地还没有时,就地建号(OA_HUB_AUTO_PROVISION)
auto_provision = true
# 应急通道出厂值(OA_HUB_LOCAL_ACCOUNTS,逗号分隔的账号名):这些账号永远只用本地
# 口令登录,不去问 Hub。真正生效的名单存在数据库 config:hub 里(系统设置那一栏,
# 保存即生效),启动时会按内置超管的账号名把它种进库、改名时也跟着搬,
# 所以这一行一般不用写:它只在库里那一行被恢复成默认之后兜底。
# 内置超管永远走本地口令,不写在这里也进得来;默认值是空串,不写死账号名,
# 免得内置超管改了名之后,这里还留着一个走本地口令的旧名字。
# local_accounts = ""
# --- 下面是老 Hub 的 Bearer token 口径:对方不给目录密钥、要求登录换 token 时才配 ---
# 配了上面的 directory_key 就都用不着;这里三项全空 + 没配密钥 = 匿名请求,
# 只在对方确实不校验目录接口的部署上拉得到。
# 长期 token(OA_HUB_SERVICE_TOKEN),找 Hub 管理员领
service_token = ""
# 集成账号(OA_HUB_SERVICE_ACCOUNT):没配 token 时用它登录换 token
service_account = ""
# 集成账号口令(OA_HUB_SERVICE_PASSWORD)
service_password = ""
# 集成账号登录时自动应答 Hub 的验证码(OA_HUB_CAPTCHA_AUTO_SOLVE),
# 只认算术型和直接回传答案的那种;答不出来会明确报"请改配长期 token"
captcha_auto_solve = true
# 目录接口是否必须带 Bearer token(OA_HUB_DIRECTORY_NEEDS_TOKEN)。默认 false;
# 老的部署要求 /directory 带 token 时打开,那时凭证换不到会直接报错而不是匿名拉
directory_needs_token = false
# 密码归 Hub 管(OA_HUB_PASSWORD_MANAGED_BY_HUB)。打开后本地不再设/改登录密码,
# 改密码入口一律提示"去 Hub 改"
password_managed_by_hub = false
# --- 统一门户免登(对接指南第 3、4 节):用户在门户点本系统卡片,带 ticket 跳回来 ---
# 本系统的应用编码(OA_HUB_APP_CODE):Hub 管理员注册应用时给的 code,也就是跳转地址
# /api/v1/auth/apps/{code}/launch 里的 {code}。票据校验回来的 app_code 与它对不上会被拒
app_code = ""
# 免登应用密钥(OA_HUB_INTEGRATION_KEY):票据校验用的密钥明文,随请求头
# X-Integration-Key 带出;Hub 只在注册/轮换那一次回显(64 位十六进制),不进代码仓库
integration_key = ""
# 落地地址要在 Hub 上登记(不在本文件里配):后端回调口径填
# https://<本系统>/api/v1/auth/sso/callback(或别名 /sso/hub),前端落地页口径填 /sso;
# 三项配齐后 GET /api/v1/hub/status 的 sso.callback_url 会回显完整地址,照抄即可
# 统一门户首页(OA_HUB_PORTAL_URL):没登录时把用户送回哪里(文档要求回 Hub 站点首页)。
# 留空就用上面的 base_url,门户与接口分域名时才需要单独填
portal_url = ""
# 应急总闸(OA_HUB_DISABLED)。true 时无视上面所有 Hub 配置,登录与同步一律回本地。
# 地址写错导致谁都登不进来时:在「系统设置 → 统一身份应急总闸」把开关拨回去保存就能恢复
# (内置超管一直走本地口令,进得来);这一项在界面上保存过就以库为准,压过下面这一行。
# 连本地账号都进不去时,在服务器上把环境变量 OA_HUB_DISABLED=true 打开再重启,
# 那时开关在界面上是灰的,只能摘掉变量再重启才解
disabled = false
# -----------------------------------------------------------------------------
# 【出厂模板】统一门户免登:登录页与 /sso 落地页的行为
# 免登要三样东西凑齐才生效:base_url + app_code + integration_key,
# 状态接口 GET /api/v1/hub/status 的 sso 段会写清楚还缺哪一项
# -----------------------------------------------------------------------------
[hub.sso]
# 允许统一门户免登(OA_HUB_SSO_ENABLED)。关掉后带 ticket 落地一律被拒
enabled = true
# 免登必须校验 state(OA_HUB_SSO_STATE_REQUIRED)。默认关掉时的口径:落地地址带了 state
# 就必须在 HttpOnly Cookie 里对得上、且与票据校验响应回传的那条一致;门户压根没带 state
# 回来(直点卡片就是这样)照旧放行。打开之后连"没带 state 回来"也一律拒,
# 而对接指南 1.4 说门户前端不解析跳转参数,先确认门户真会把 state 原样带回来再打开
state_required = false
# -----------------------------------------------------------------------------
# 【出厂模板】统一身份权限:系统设置页 →「统一身份权限」,保存即生效
# 角色 / 权限码 / 数据范围向 Hub 要口径(《Hub 权限接口交互文档》第 3~8 节)。
# 默认关闭:关着的时候权限完全按本系统的角色矩阵走,一次 Hub 都不问。
# 前置条件是上面的 enabled = true 且 base_url 已填 —— 权限接口复用的是登录那套凭证。
# -----------------------------------------------------------------------------
[hub.perm]
# 启用统一身份权限(OA_HUB_PERM_ENABLED)
enabled = false
# 怎么用(OA_HUB_PERM_MODE):shadow = 只把 Hub 的口径显示出来对账,判定仍按本地角色矩阵;
# enforce = 以统一身份为准,Hub 说没有这个权限码就没有
mode = "shadow"
# 问 Hub 要哪个应用的权限(OA_HUB_PERM_APPLICATION_ID),即文档里的 application_id。
# 留空用上面 [hub] 免登那个 app_code
application_id = ""
# 权限缓存时长(秒)(OA_HUB_PERM_CACHE_SECONDS)。文档第 3 节允许业务系统自行缓存权限,
# 但失效要自己负责;0 = 每个请求现问(只在测试环境这么干)
cache_seconds = 60
# 数据范围口径(OA_HUB_PERM_SCOPE_MODE):merge = 本地角色与 Hub 各给一个范围时取更大的;
# hub = 完全照 Hub 给的
scope_mode = "merge"
# 没有用户令牌时由服务端代查(OA_HUB_PERM_ADMIN_QUERY)。免登进来的人本系统手上没有 Hub
# 令牌,问不了 /me/*,打开后用同步凭证走 admin/users/{id}/roles 代查
admin_query = true
# Hub 一个本系统认得的权限码都没给时保留本地权限(OA_HUB_PERM_KEEP_LOCAL)。
# 免得权限还没登记、角色还没绑的时候把所有人锁在门外
keep_local = true
# 权限相关接口路径同样不写死在代码里(站点地址仍用上面的 base_url)。
# {role_id} / {user_id} 两个占位符在调用时才填值,占位符写坏了会退回出厂路径。
[hub.perm.api]
# 当前用户角色(OA_HUB_PERM_PATH_ROLES):文档第 5 节
roles = "/api/v1/auth/me/roles"
# 当前用户权限(OA_HUB_PERM_PATH_PERMISSIONS):文档第 6 节,带 application_id 查询参数
permissions = "/api/v1/auth/me/permissions"
# 当前用户数据范围(OA_HUB_PERM_PATH_DATA_SCOPE):文档第 7 节
data_scope = "/api/v1/auth/me/data-scope"
# 按数据权限导出组织人员(OA_HUB_PERM_PATH_DIRECTORY_SCOPED):文档第 11 节
directory_scoped = "/api/v1/auth/directory/scoped"
# 角色目录(OA_HUB_PERM_PATH_ADMIN_ROLES):文档第 8 节
admin_roles = "/api/v1/auth/admin/roles"
# 权限目录,查询与登记共用这一条(OA_HUB_PERM_PATH_ADMIN_PERMISSIONS):文档第 8 节
admin_permissions = "/api/v1/auth/admin/permissions"
# 角色绑定的权限(OA_HUB_PERM_PATH_ADMIN_ROLE_PERMISSIONS):文档第 8 节
admin_role_permissions = "/api/v1/auth/admin/roles/{role_id}/permissions"
# 用户的角色(OA_HUB_PERM_PATH_ADMIN_USER_ROLES):文档第 8 节
admin_user_roles = "/api/v1/auth/admin/users/{user_id}/roles"
# 指定用户的数据范围(OA_HUB_PERM_PATH_ADMIN_USER_DATA_SCOPE):文档第 7 节
admin_user_data_scope = "/api/v1/auth/admin/users/{user_id}/data-scope"
# -----------------------------------------------------------------------------
# 【出厂模板】Hub 接口路径:系统设置页 →「统一身份登录」,保存即生效
# 这些接口默认按《dsh-hub 统一门户 第三方系统对接指南》的路径调用,路径一律不写死在代码里。
# Hub 换了前缀、挂在网关反向代理后面、或者改版换了路径,改这里(或在系统设置页
# 改同名项)就够了:存进数据库、立刻生效,不用改代码也不用重启。
# 只写路径部分(以 / 开头);站点地址仍然是上面 [hub] 的 base_url。
# -----------------------------------------------------------------------------
[hub.api]
# 登录验证码(OA_HUB_PATH_CAPTCHA):GET {base_url}{captcha},登录页要验证码时就调它
captcha = "/auth/captcha"
# 账号密码登录(OA_HUB_PATH_LOGIN):POST {base_url}{login},账号密码由 Hub 判定
login = "/auth/login"
# 校验 token(OA_HUB_PATH_VERIFY_TOKEN):POST {base_url}{verify_token},
# 登录拿到 token 之后复核一次;该接口恒返回 200,看 data.active
verify_token = "/api/v1/auth/token/verify"
# 当前用户(OA_HUB_PATH_ME):GET {base_url}{me},Hub 用户首次登录建号时用它取部门
me = "/api/v1/auth/me"
# 全量组织人员(OA_HUB_PATH_DIRECTORY):GET {base_url}{directory},
# 夜间定时同步与界面上的「立即同步」都拉这一个
directory = "/api/v1/auth/directory"
# 组织人员变更流水(OA_HUB_PATH_DIRECTORY_CHANGES):GET {base_url}{directory_changes},
# 增量同步按游标轮询这一个(对接指南第 6.2 节)
directory_changes = "/api/v1/auth/directory/changes"
# 免登票据校验(OA_HUB_PATH_TICKET_VERIFY):POST {base_url}{ticket_verify},
# 只由本系统后端带 X-Integration-Key 调用,浏览器不参与(对接指南第 4 节)
ticket_verify = "/api/v1/auth/tickets/verify"
# 可见应用列表(OA_HUB_PATH_APPS):GET {base_url}{apps},统一门户落地页的数据源,
# 要用户登录态;本系统只用它自检门户通不通,不在自己的界面上列应用
apps = "/api/v1/auth/apps"
# 发起免登跳转(OA_HUB_PATH_LAUNCH):POST {base_url}{launch},
# {code} 调用时换成本系统的应用编码(app_code)
launch = "/api/v1/auth/apps/{code}/launch"
# 企业微信消息推送(OA_HUB_PATH_NOTIFY_WECOM):POST {base_url}{notify_wecom} 发消息,
# GET 同一路径 + /{msg_key} 回查逐人投递结果;用的就是上面免登那把 X-Integration-Key,
# 本系统不持有企业微信密钥。「消息通知」里的 hub_wecom 渠道走这一条(见 docs/hub-integration.md §15)
notify_wecom = "/api/v1/auth/notify/wecom/messages"
# -----------------------------------------------------------------------------
# 【出厂模板】组织人员同步:系统设置页 →「同步定时任务」,保存即生效
# 从 Hub 的 GET /api/v1/auth/directory 拉全量落库,多久拉一次由下面 when 决定
# -----------------------------------------------------------------------------
[hub.sync]
# 「允许定时同步」这个总开关**不在配置文件里**:它只在界面上配(系统设置 →
# 同步定时任务),文件与环境变量写了都不生效,启动日志还会点名提醒。
# 以前它能被出厂值或部署模板关掉,结果定时任务悄悄不跑、界面上查不出是谁关的。
# 下面这些是出厂排期,界面上存过之后以界面为准。
# 同步频率(OA_HUB_SYNC_WHEN):daily 每天 / weekly 每周选几天 /
# monthly 每月选几天 / interval 按间隔。写错回落到 daily
when = "daily"
# 本地时间 HH:MM 跑(OA_HUB_SYNC_TIME),写错回落到 01:00;
# 只有 interval 那一档不看这一项
time = "01:00"
# 每周哪几天(OA_HUB_SYNC_WEEKDAYS):只在 when = "weekly" 时起作用,
# 1=周一 … 7=周日,可多选;一个都没认出来时退回周一到周五
weekdays = ["1", "2", "3", "4", "5"]
# 每月哪几天(OA_HUB_SYNC_MONTHDAYS):只在 when = "monthly" 时起作用,取值 1-31;
# 当月没有 30/31 号就顺延到当月最后一天,不会整月一次都不跑
monthdays = ["1"]
# 按间隔:隔多少分钟再跑(OA_HUB_SYNC_INTERVAL_MINUTES):只在 when = "interval" 时
# 起作用,从上一趟跑完开始计时,取值 30-43200。这一档每次都是全量导出,别调太小
interval_minutes = 1440
# 同步部门(OA_HUB_SYNC_ORGS)。关掉则只同步人员,不动 oa_unit
orgs = true
# 按编码认领本地自建部门(OA_HUB_SYNC_BIND_LOCAL_BY_CODE)。
# 本系统自己加的部门,只要组织编码跟 Hub 某个部门一模一样且本地这个编码只用了一次,
# 同步就认成同一个部门(补上 hub_org_id),不再另建一个重名部门;认下之后名称与层级
# 归 Hub 管,负责人、排序、说明、简称还是本地说了算。编码撞车就跳过并写进同步记录。
bind_local_by_code = true
# 带上 Hub 已停用的组织(OA_HUB_SYNC_INCLUDE_DISABLED_UNITS,即
# include_disabled=true),否则整棵停用的子树都拿不到
include_disabled_units = true
# Hub 里已消失的同步账号置为「已停用」(OA_HUB_SYNC_OFFBOARD)。
# 只停用不删除,本地账号永不受影响
offboard = true
# 离职停用熔断(OA_HUB_SYNC_OFFBOARD_GUARD_PERCENT,取值 0-95):一趟同步里等着停用的人
# 超过本地同步账号总数的这个百分比、并且超过 20 人时,这一趟一个人都不停用,只报数并把
# 该趟标成「部分完成」。Hub 换环境、重导数据、或目录清单出问题时最容易撞上——它会把整家
# 公司一次性判成离职,而权限与待办不会自己长回来。核对过清单确实没错,再调大或设 0 关掉。
# 同一个百分比也管部门侧:一趟要停用的部门超过 max(5, 同步部门数 × 百分比) 时一个都不停
offboard_guard_percent = 40
# 熔断线的人数底线(OA_HUB_SYNC_OFFBOARD_GUARD_MIN_PEOPLE,取值 0-5000):熔断线取
# 「同步账号总数 × 百分比」与这个数里的较大者,所以小部署裁掉几个人不会被比例挡下来。
# 几十人的团队想让它更早触发就调小,上千人的部署嫌 20 太松可以调大;0 = 只看百分比
offboard_guard_min_people = 20
# 部门侧熔断线的个数底线(OA_HUB_SYNC_UNIT_OFFBOARD_GUARD_MIN,取值 0-5000):部门总数比
# 人少一个量级,沿用人员那侧的 20 这条线永远不会触发,等于没有熔断。0 = 只看百分比
unit_offboard_guard_min = 5
# 让"已查无此人"的账号腾出登录名(OA_HUB_SYNC_RECLAIM_LOST_ACCOUNTS)。Hub 合并/重导人员后
# 会把账号名挪到另一个 user_id 上,占着名字的本地行绑的却是已删除的 user_id(Hub 的变更
# 流水不记删除),同步又不许抢别人的账号,活着的人就永远拿不回登录名、每一趟都撞一次车。
# 打开后,"本地已停用 + 这一趟完整清单里查无此人"的同步账号会把名字腾开(改成
# hub-lost-<user_id>-<原名>),人、待办、按主键挂的权限都不动。关掉就退回"只报数不处理"
reclaim_lost_accounts = true
# 让位名单的清单人数下限(OA_HUB_SYNC_ROSTER_FLOOR_PERCENT,取值 0-100):Hub 这次回的
# 人员数不足「可参照基准 × 这个百分比」时,认定目录正在被清空或重导,这一趟一个登录名
# 都不让位(撞车照旧只报数)。基准取「上次同步记下的人数」与「本地带 Hub 主键的账号数」
# 里较小但仍然可信的那个。实测 2026-11-05 测试站一天之内从 100 人掉到 1 人,靠这一条
# 挡住了把上百个登录名一次性刷成 hub-lost-*。0 = 不设下限
roster_floor_percent = 50
# permission_version 与上次一致时跳过写入(OA_HUB_SYNC_SKIP_UNCHANGED)。
# 只作用于排期跑的那趟;界面上的「立即同步」永远强拉
skip_unchanged = true
# 单次导出人员上限(OA_HUB_SYNC_MEMBER_LIMIT),取值 1-5000。
# 人比这多就调大,别靠截断结果跑同步(截断的这一趟只写不撤)
member_limit = 5000
# 同步建号时按 账号@域名 补邮箱(OA_HUB_SYNC_EMAIL_DOMAIN),留空不补;
# Hub 的人员清单不带邮箱
email_domain = ""
# 本地 role=admin 的账号不参与同步(OA_HUB_SYNC_PROTECT_ADMINS),
# 防止被 Hub 改名、换部门或停用
protect_admins = true
# 排期那趟失败后的补试间隔(分钟)(OA_HUB_SYNC_RETRY_MINUTES)
retry_minutes = 10
# 当天最多补试几次(OA_HUB_SYNC_RETRIES),超过就只留一条失败记录
retries = 3
# -----------------------------------------------------------------------------
# 【出厂模板】组织人员增量同步:变更流水轮询
# 排期那趟全量是"每日校对",这一组负责把人与人、部门与部门的改动尽快落本地:
# 按游标轮询 GET /api/v1/auth/directory/changes(对接指南第 6.2、6.3 节),
# 同一批循环拉到 has_more=false 才提交游标;游标推不动了就改拉一次全量重对齐。
# 状态接口 GET /api/v1/hub/status 的 changes 段能看到游标走到哪、还差多少条
# -----------------------------------------------------------------------------
[hub.sync.changes]
# 增量同步总闸(OA_HUB_SYNC_CHANGES_ENABLED)。关掉只剩排期全量 + 界面上的「立即同步」
enabled = true
# 轮询周期(秒)(OA_HUB_SYNC_CHANGES_INTERVAL_SECONDS)。文档建议 30-60 秒;
# 后台调度线程每分钟醒一次,所以实际间隔不会小于这个周期
interval_seconds = 45
# 单批条数(OA_HUB_SYNC_CHANGES_LIMIT),取值 1-500(Hub 侧上限 500)
limit = 200
# 落后过多就回全量(OA_HUB_SYNC_CHANGES_FULL_ON_GAP)。流水被裁剪、本系统停机过久,
# 或收到只带 id 与 status/parent_id 的组织变更事件时,直接改拉一次全量(文档第 6.4 节);
# 关掉就只记日志、等排期那趟全量校对补齐
full_on_gap = true
# -----------------------------------------------------------------------------
# 【出厂模板】大模型能力:系统设置页 →「大模型能力」,保存即生效
# 这一组只管「能不能调、失败补几次、日志记多细」。接入本身(服务商、接口地址、
# 密钥、模型清单、启停与默认)不在配置文件里,一条一行存在 oa_ai_provider 表里,
# 界面上在 系统设置 -> 大模型接入 页面维护;对接口径见 docs/llm-integration.md
# -----------------------------------------------------------------------------
[ai]
# 总闸(OA_AI_ENABLED)。false = 业务功能一律不去调大模型。
# 关掉不影响「大模型接入」页面上的「测试连通」与试运行 —— 那两个是用来先把接入
# 配好验通、再打开总闸的;接入列表本身的增删改也不受这一项限制。
enabled = false
# 调用失败补试次数(OA_AI_RETRIES),取值 0-5,0 = 不补试。
# 只对「连不上、超时、对方 5xx、被限流」这类错误重试;参数被拒、密钥不对这种
# 一定失败的直接报错,不浪费时间。
retries = 2
# 日志里记提示词原文(OA_AI_LOG_PROMPT)。打开后运行日志带上发给模型的提示词与
# 回复(各截断 400 字),排查「模型答得不对」时好用。提示词里可能有内部数据,
# 默认只记长度不记内容,生产环境按需打开。
log_prompt = false
# -----------------------------------------------------------------------------
# 【出厂模板】文件存放位置:系统设置页 →「文件存放位置」,保存即生效
# · 表单「上传附件」与首页「信息资讯」(封面图 + 正文附件)一律进 MinIO
# · 「网盘」文件暂不参与配置,固定落在本地磁盘 [storage.local]
# · 数据库里只存 uri(minio://桶/键、local://相对路径),换存储或改上传路径
# 都不用洗库:已有对象按各自的 uri 继续读
# -----------------------------------------------------------------------------
[storage]
# 上传文件总大小上限(MB)(OA_MAX_UPLOAD_MB),0 = 不限制
max_upload_mb = 200
# 扩展名白名单(OA_ALLOWED_EXTENSIONS,逗号分隔),空数组 = 不限制。
# 例:["pdf", "docx", "xlsx", "png", "jpg", "zip"]
allowed_extensions = []
# MinIO 连不上时是否退回本地磁盘(OA_STORAGE_FALLBACK)。
# true = 落本地并在日志里告警,宁可少用对象存储也不让上传整个失败;
# false = 直接报错,宁可上传失败也不落错地方
fallback_to_local = true
# -----------------------------------------------------------------------------
# 【出厂模板】本地磁盘:网盘文件的位置,也是 MinIO 故障时的兜底落点
# 界面上「文件存放位置」改的是配置项 local_root,保存即生效
# -----------------------------------------------------------------------------
[storage.local]
# 相对 backend/ 的目录(OA_LOCAL_ROOT),写绝对路径也可以
root = "storage"
# -----------------------------------------------------------------------------
# 【出厂模板】MinIO:上传附件 + 信息资讯的落点
# 界面上「文件存放位置」改这些(存进 config:storage,保存即生效,
# MinIO 客户端会按新参数自动重建,不用重启)
# 群晖 S3 兼容对象存储、阿里云 OSS、AWS S3 同样适用,只改 endpoint / bucket
# -----------------------------------------------------------------------------
[storage.minio]
# 只写 主机:端口,不要带 http:// 前缀(OA_MINIO_ENDPOINT)。
# S3 API 端口一般是 9000(控制台是 9001)
endpoint = "127.0.0.1:9000"
# Access Key(OA_MINIO_ACCESS_KEY)
access_key = "minioadmin"
# Secret Key(OA_MINIO_SECRET_KEY)。接口只把它当输入,永不回显
secret_key = ""
# 桶名(OA_MINIO_BUCKET)。后端不会自动建桶,请先在 MinIO 控制台建好并设为 private
bucket = "unis-oa"
# 走 HTTPS 时改成 true(OA_MINIO_SECURE)。endpoint 是 9000 这类 S3 API 端口时通常为 false
secure = false
# 上传路径(OA_MINIO_UPLOAD_PATH):对象键前缀,文件落在桶里这个目录下,
# 完整对象键是 <上传路径>/<用途>/<YYYYMM>/<uuid>.<ext>;留空 = 直接放桶根
upload_path = "uploadPath"
# 区域(OA_MINIO_REGION)。MinIO 不校验,保持 us-east-1
region = "us-east-1"
# 预签名直链有效期(秒)(OA_MINIO_PRESIGNED_TTL)。
# 0 = 下载一律经过后端鉴权代理(推荐,权限最稳)
presigned_ttl_seconds = 0
# 浏览器可直连的域名(OA_MINIO_PUBLIC_BASE_URL),用于预签名链接;留空则用 endpoint
public_base_url = ""
# 建连超时(秒)(OA_MINIO_CONNECT_TIMEOUT)
connect_timeout_seconds = 10
# 读超时(秒)(OA_MINIO_READ_TIMEOUT)
read_timeout_seconds = 60
# -----------------------------------------------------------------------------
# 【出厂模板】共享缓存与限流:系统设置页 →「共享缓存与限流(Redis)」,保存即生效
# Redis 是**可选件**:地址留空 = 整套不启用,功能一个不少,只是退回"每个进程各有一份
# 缓存、限流靠查库数一分钟、配置失效最多等 2 秒快照周期"的单进程口径。
# 多副本部署(uvicorn --workers N,或两台机器挂在负载均衡后面)才真需要它:
# · 外部取数结果、Hub 服务令牌、Hub 权限、字典选项 —— 各副本共用一份,不会同一个人的
# 权限被问 N 遍、同一个上游被 N 个副本各取一次
# · 开放接口与外部数据源的「每分钟 N 次」由一个共享计数器判,副本数不再把额度放大
# · 界面上改了配置 / 数据源 / 字典,其它副本当场跟上
# 连不上、超时、命令报错都自动退回上面那套老口径,只在日志里喊一声,不影响业务;
# 哪些东西刻意不放 Redis(审批租约、单据编号、额度账本、权限判定结果)见 app/cache.py
# 顶部与 docs/redis-integration.md
# -----------------------------------------------------------------------------
[redis]
# 总闸(OA_REDIS_ENABLED)。关掉或把地址留空都能停掉这一层,界面上改,保存即生效
enabled = true
# 连接串(OA_REDIS_URL)。填了就忽略下面几项:redis://:口令@127.0.0.1:6379/0,
# 要 TLS 用 rediss://user:口令@host:6380/1。接口从不回显明文
url = ""
# 地址(OA_REDIS_HOST):主机名或 IP,不带 redis:// 前缀与端口。**留空 = 不启用**
host = ""
# 端口(OA_REDIS_PORT)
port = 6379
# 库号(OA_REDIS_DB),0-15。一台 Redis 给多个环境用时,各环境用自己的键前缀更稳
db = 0
# ACL 用户名(OA_REDIS_USERNAME)。只配了 requirepass 时这里留空、只填口令
username = ""
# 口令(OA_REDIS_PASSWORD)。接口只把它当输入,永不回显;更省心的做法是用环境变量注入
password = ""
# 键前缀(OA_REDIS_KEY_PREFIX)。所有键都长这样:unisoa:fetch:ERP_BALANCE:9f3a…
key_prefix = "unisoa"
# 读写超时(秒)(OA_REDIS_TIMEOUT)。宁可短:Redis 卡住时这一层要立刻让路给数据库,
# 而不是把每个请求都拖住
socket_timeout_seconds = 2
# 每进程连接池上限(OA_REDIS_MAX_CONNECTIONS)。副本数 × 这个数别超过 Redis 的 maxclients
max_connections = 32
# 限流计数走 Redis(OA_REDIS_RATE_LIMIT)。关掉或 Redis 不可用时自动退回查调用留痕表
rate_limit_enabled = true
# 失效广播走 Redis(OA_REDIS_BROADCAST)。关掉就靠各自的快照周期到点重读
broadcast_enabled = true
# 字典选项(下拉、级联那些)在副本之间共享的秒数(OA_REDIS_DICT_CACHE)。改了字典会当场
# 失效,不用等这里的时间;0 = 不共享,每次现查库
dict_cache_seconds = 60
# -----------------------------------------------------------------------------
# SQL 取数(「外部数据源」页那条 provider=sql 的通道)
# 为什么要有这一条通道:值在自己的库里、又没有一个接口给它,以前只能等研发加接口;
# 现在管理员写一条只读 SELECT 就能配出「带出什么值」。设计见 docs/sql-autofill-design.md
# 这一组只有这两项,而且界面上没有对应的一栏:这条通道读的是本库,开不开、用哪个账号,
# 该由部署的人决定一次。改完重启(它不进数据库,也就不会被谁在界面上顺手改掉)。
# 行数与超时不在这里配:一次最多回 200 行写在 app/service/sqlsource.py,
# 跑多久按那张数据源自己的「超时秒数」——一个数只管一处,配的人不用猜哪份说了算。
# -----------------------------------------------------------------------------
[data_source.sql]
# 总闸(OA_SQL_ENABLED)。默认关:关掉不影响 http / mock / 流程数据那三条通道,
# 只是 SQL 源会当场取不出值并说清楚原因
enabled = false
# 可选的加固项(OA_SQL_DSN)。形如 mysql+pymysql://reader:口令@127.0.0.1:3306/unis_oa?charset=utf8mb4。
# 填了就给这条通道单开一条独立的小连接池连这个账号(不与平台主池抢:一条没写 WHERE 的
# 大表扫描只堵自己那几条连接);留空 = 用平台连库的那个账号,此时只靠「只读事务 +
# 只允许 SELECT」兜底。生产建议单开一个只有 SELECT 权限的账号填这里
dsn = ""
# -----------------------------------------------------------------------------
# 【表单嵌外部页面】表单设计里的「外部页面」那一格(type=embed)开的是别的业务系统
# 的页面,同一个功能就不用在 OA 再开发一遍。设计见 docs/embed-page-field-design.md
# 这一组和上面那组一样不进系统设置页:CSP 是整站级别的响应头,改错一次会让所有页面
# 都打不开,不该让人在界面上手滑。改完重启。
# 页面地址与密钥本身不在这里配,在「外部数据源」页登记 provider=可嵌入页面 那一条
# -----------------------------------------------------------------------------
[embed]
# 总闸(OA_EMBED_ENABLED)。关掉之后表单上那一格只说一句"这个功能当前没开",
# 已登记的页面和已发布的表单都不受影响,不用回滚表单
enabled = true
# 要不要下发 CSP 那两道头(OA_EMBED_CSP)。frame-src 的白名单来自「外部数据源」里
# 启用中的那些页面地址,再加下面 frame_extra;'self' 与 blob: 永远带着——blob: 是
# 附件预览把 PDF 塞进 iframe 在用那条路,漏了它附件预览整块打不开。
# frame-ancestors 'none' 是顺手补的:OA 自己任何时候都不该被别人嵌。
# 排查"某个页面突然打不开"时先把它关了再试,能立刻分清是不是这道头挡的
csp = true
# 注册表之外再允许哪几个来源被嵌(OA_EMBED_FRAME_EXTRA,逗号分隔,也支持写成数组)。
# 只给"这个环境要留一个不去注册表登记的地址"那种场合用,平时留空
frame_extra = []
# 免登短码的存活秒数(OA_EMBED_TICKET_TTL)。「本系统发短码」那一档发出去的短码只能
# 用一次,这一档说的是它在被用掉之前能等多久——对方服务端要在这段时间内拿它来换身份。
# 出厂 60 秒;对方系统冷启动慢可以放到 120,别放到分钟级:它是往人家系统里递身份的钥匙
ticket_ttl = 60