角色，配錯(cuò)一步照樣裸奔)
自托管Treg的密鑰暗礁Fernet加密、ACL與四級(jí)角色配錯(cuò)一步照樣裸奔【免費(fèi)下載鏈接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn項(xiàng)目地址: https://gitcode.com/GitHub_Trending/treg/treg把 3000 個(gè)外部 API 端點(diǎn)收斂到一個(gè)網(wǎng)關(guān)、把幾十家供應(yīng)商的密鑰托管在服務(wù)器上——treg 這套OpenRouter for agent tools的設(shè)計(jì)聽(tīng)起來(lái)很美Agent 只需一個(gè) token就能替你調(diào)用 SEO、社媒、廣告、數(shù)據(jù)富集等真實(shí)世界的工具密鑰永不出服務(wù)器。但密鑰不出服務(wù)器有個(gè)前提服務(wù)器上那一坨加密落盤的密鑰以及決定誰(shuí)能用它們的那套權(quán)限必須配得對(duì)。社區(qū)里流傳的各種 treg 教程大多停留在怎么把一個(gè) token 調(diào)通的層面真正讓自托管實(shí)例裸奔的往往是四件事Fernet 主密鑰沒(méi)設(shè)或丟了、角色權(quán)限給了寬、審計(jì)日志根本沒(méi)被當(dāng)成安全數(shù)據(jù)看、以及部署時(shí)踩了那些默認(rèn)值暗坑。這篇基于 treg 倉(cāng)庫(kù)源碼逐一拆解最后給一份可以直接照著執(zhí)行的自檢清單。一、Fernet 主密鑰全庫(kù)密鑰的總開(kāi)關(guān)treg 落盤加密選的是 Fernet——對(duì)稱加密一個(gè) 32 字節(jié) urlsafe base64 主密鑰加密所有 Secret 值?？?crypto.py 的實(shí)現(xiàn)整個(gè)模塊只有幾十行def _fernet() - Fernet: key get_settings().secret_key return Fernet(key.encode() if key else _EPHEMERAL) def encrypt(plaintext: str) - str: return _fernet().encrypt(plaintext.encode()).decode() def new_key() - str: return Fernet.generate_key().decode()關(guān)鍵就在_fernet()里那個(gè)兜底secret_key為空時(shí)進(jìn)程會(huì)現(xiàn)場(chǎng)鑄一把臨時(shí)密鑰_EPHEMERAL。這意味著什么沒(méi)配TREG_SECRET_KEY的服務(wù)照樣能跑、密鑰照樣加密落盤——但重啟后所有密文都無(wú)法解密。這不是悄悄丟失而是一個(gè)響亮的安全信號(hào)代碼注釋原話是secrets wont survive a restart, which is the intended loud signal to set TREG_SECRET_KEY。更狠的防線在 infra/db.py 的verify_db()if not settings.secret_key and sqlite not in settings.database_url: raise RuntimeError( TREG_SECRET_KEY is not set on a non-SQLite database - stored secrets would be lost on the next restart. Set a key (treg keygen) before starting. )也就是說(shuō)SQLite 本地模式允許臨時(shí)密鑰反正數(shù)據(jù)在本機(jī)、丟了重連即可但只要你不是 SQLite啟動(dòng)直接拒絕。這個(gè)設(shè)計(jì)堵住了拿 Postgres 當(dāng)生產(chǎn)庫(kù)卻不設(shè)密鑰的最蠢路徑。生成與保存密鑰的正確姿勢(shì)倉(cāng)庫(kù)自己給的 self-host 腳本寫得很標(biāo)準(zhǔn)見(jiàn) selfhost.shKEY$($VENV/bin/python -m treg keygen) cat $ENV_FILE EOF TREG_SECRET_KEY$KEY EOF chmod 600 $ENV_FILEpython -m treg keygen見(jiàn)main.py就是new_key()的 CLI 出口.env權(quán)限收成 600。這套流程值得照抄因?yàn)榇蟛糠肿酝泄苁鹿是∏》粗鴣?lái)密鑰明文進(jìn) shell history、.env 權(quán)限 644、或者干脆沒(méi)設(shè)。輪換主密鑰輪換其實(shí)無(wú)解所以要在鑰匙環(huán)里做文章必須直說(shuō)一個(gè)殘酷事實(shí)treg 的 Fernet 主密鑰不支持原地輪換。encrypt()與decrypt()用的是同一個(gè)TREG_SECRET_KEY一旦換新密鑰舊密文全部解不開(kāi)唯一的補(bǔ)救是重新錄入/重連所有供應(yīng)商密鑰。倉(cāng)庫(kù)文檔auth-secrets.md和代碼都沒(méi)有提供雙密鑰滾動(dòng)解密的能力。所以對(duì)自托管者而言密鑰輪換的現(xiàn)實(shí)答案分兩層主密鑰層面能做的只有用 KMS/密鑰管理服務(wù)注入環(huán)境變量 文件權(quán)限 600 備份到密碼管理器把TREG_SECRET_KEY當(dāng)根 CA 私鑰一樣對(duì)待。丟了它 丟了一庫(kù)供應(yīng)商憑據(jù)。真正的輪換粒度在 API Key 層面treg 把誰(shuí)調(diào)用的憑據(jù)treg_xxx開(kāi)頭的 token和調(diào)用什么的供應(yīng)商憑據(jù)分開(kāi)管理。調(diào)用方 token 只存 SHA-256 哈希hash_token()見(jiàn) crypto.py庫(kù)中永遠(yuǎn)沒(méi)有明文 token輪換走rotate_agent_key/rotate_human_keyapi_keys.py用條件 UPDATE 做跨進(jìn)程原子占鎖result await db.execute( update(ApiKey).where( ApiKey.id old.id, ApiKey.state.in_((ACTIVE, DISABLED)), ApiKey.replacement_key_id.is_(None), ).values(stateREVOKED, revoked_atnow, deleted_atnow) ) if result.rowcount ! 1: raise RotationConflict舊行置為REVOKED并掛replacement_key_id舊 token 當(dāng)場(chǎng)失效同時(shí)保留審計(jì)痕跡。對(duì)Default key每名成員每團(tuán)隊(duì)一張的簽名 token輪換走default_generation自增rotate_default_generationtoken 里簽的kgclaim 對(duì)不上就直接 401revoked key。教訓(xùn)把輪換的預(yù)期放在調(diào)用方 token 上而不是主密鑰上。主密鑰設(shè)計(jì)成不可輪換意味著你必須保證它從一開(kāi)始就不會(huì)泄露——這比能輪換更考驗(yàn)部署紀(jì)律。另外注意 config.py 里一個(gè)極易被忽略的細(xì)節(jié)session_secret簽名會(huì)話 cookie 的 HMAC 密鑰未設(shè)置時(shí)回退到secret_key。也就是說(shuō)如果你只設(shè)了一個(gè)強(qiáng)secret_key而session_secret為空那么拿到secret_key的人同時(shí)能偽造會(huì)話 cookie——密鑰隔離形同虛設(shè)。生產(chǎn)環(huán)境兩個(gè)都應(yīng)顯式設(shè)置成不同的隨機(jī)值。二、四級(jí)角色與 ACL最危險(xiǎn)的權(quán)限不是給了 admintreg 的角色模型是四級(jí)owner admin member viewer定義在 models.pyROLE_RANK {viewer: 0, member: 1, admin: 2, owner: 3}角色的分界點(diǎn)在哪里看 access.py 的_require_can_registerdef _require_can_register(caller: Caller) - None: if not _role_at_least(caller.role, member): raise HTTPException(status_code403, detailviewers can call and read, but cannot register)一句話概括viewer 能調(diào)用、能讀但什么都不能注冊(cè)不能建 Secret、不能注冊(cè)工具、不能發(fā)起 OAuth。routers/api_keys.py里 viewer 連創(chuàng)建附加 key都被拒絕viewers cannot create additional keys。invite 的--role可選值也只有viewer/member/admincli.pyowner 只能通過(guò)改角色接口授予。兩個(gè)最容易被誤解的坑坑一owner 不受任何 ACL 限制而 deny 規(guī)則連 owner 都攔?？?access.pydef _tool_allowed(caller: Caller, tool_name: str) - bool: if caller.role owner: return True access caller.membership.tool_access return access is None or tool_name in accessowner 在工具級(jí) ACL 和項(xiàng)目級(jí) ACL_project_allowed面前一律放行——這是刻意的owner is never restricted但意味著把一個(gè)人升成 owner就等于把團(tuán)隊(duì)所有密鑰的使用權(quán)都交給他。反過(guò)來(lái)enforce_deny的注釋寫得明明白白deny 規(guī)則對(duì)包括 owner 在內(nèi)的所有角色生效因?yàn)閐eny rule is a guardrail, not a permission tier。坑二四級(jí)角色只是注冊(cè)權(quán)限的標(biāo)尺真正的精細(xì)管控在 Membership 行上。每個(gè)成員有一行Membershipmodels.py上面可以單獨(dú)釘三樣?xùn)|西tool_accessNULL 團(tuán)隊(duì)全部工具JSON 列表 只允許列出的工具project_accessNULL 整個(gè) orgJSON 列表 只允許這些項(xiàng)目里的工具daily_call_cap每人每日調(diào)用上限-1 不限配合local_run_enabled控制能否走本地 run 授權(quán)。兩把 ACL 鎖的關(guān)系是AND 組合_tool_usable_tool_allowed且_project_allowed。換句話說(shuō)最小權(quán)限的正確姿勢(shì)不是給 viewer 還是 member而是給協(xié)作方 member 角色 tool_access釘?shù)絺€(gè)別工具 project_access釘?shù)絾蝹€(gè)項(xiàng)目 daily_call_cap設(shè)上限。四級(jí)角色管能不能注冊(cè)ACL 管能用哪些缺一不可。還有一個(gè)隱蔽的坑invite 接口models.py 的Invite在tool_access字段上就能預(yù)置 ACL——發(fā)邀請(qǐng)時(shí)就釘好工具名單而不是等人進(jìn)來(lái)再逐項(xiàng)改。自托管團(tuán)隊(duì)如果靠先發(fā) member 邀請(qǐng)、事后收權(quán)邀請(qǐng)窗口期就是權(quán)限敞口。別忽視機(jī)器身份這條暗線treg 里 Agent 是不可登錄的機(jī)器身份郵箱掛在agents.treg.local這種不可路由域上access.py任何登錄門都解析不到它而它作為 User 卻能繼承 Membership 的所有能力。require_identity里專門防了一手if user is not None and _is_machine_email(user.email): raise HTTPException(status_code403, detail( this token belongs to a machine identity — it can call this teams tools, but cannot act as a user))機(jī)器 token 不能建 org、不能收邀請(qǐng)——因?yàn)闄C(jī)器能建 org 就自動(dòng)成為 ownerowner 又豁免所有 ACL。這是倉(cāng)庫(kù)里自己寫明的逃逸路徑自托管時(shí)給 Agent 發(fā) key 也請(qǐng)遵循同樣的最小權(quán)限專用 token、釘死的tool_access、獨(dú)立的daily_call_cap。三、審計(jì)日志的盲區(qū)它是盡力而為的不是證據(jù)鏈如果你把CallRecordmodels.py當(dāng)誰(shuí)在什么時(shí)候調(diào)了什么的完整賬本那就踩進(jìn)最大的盲區(qū)了。審計(jì)子系統(tǒng)audit.py的設(shè)計(jì)哲學(xué)模塊 docstring 第一句就是Audit writes — deferred and fire-and-forget (rule #2: never block the proxied response).具體機(jī)制是單進(jìn)程單 writer、批量落庫(kù)、后臺(tái)連接池以及背壓丟行_MAX_PENDING 5000 # shed load past this: drop the audit row rather than grow unbounded _BATCH 200隊(duì)列超過(guò) 5000 條就直接丟審計(jì)行只記一個(gè)遞增計(jì)數(shù)器并打日志。這是刻意的取舍——audit is best-effort; never OOM or wedge the server for it。所以審計(jì)表可能缺行。峰值流量下丟的正是最需要查的那幾筆。做安全復(fù)盤時(shí)不能把審計(jì)表里沒(méi)有當(dāng)成沒(méi)發(fā)生。審計(jì)與計(jì)費(fèi)分離。CallRecord注釋明確錢在 ledger 里同步落地審計(jì)表是允許丟行的分析數(shù)據(jù)the money landed in the ledger synchronously... losing a row here costs analytics, not accounting。查成本走 ledger查行為走 audit兩套數(shù)據(jù)源對(duì)不齊時(shí)別慌。失敗靜默但有 ERROR 日志。寫庫(kù)失敗不會(huì)打斷調(diào)用an audit hiccup must never break a real call但會(huì)打ERROR級(jí)日志。運(yùn)維上必須把 treg 的 ERROR 日志當(dāng)警報(bào)接住——正常流量下 audit writer 不該報(bào)錯(cuò)一旦出現(xiàn)說(shuō)明審計(jì)鏈路已破。對(duì)安全審計(jì)而言更值得盯的三張表/字段ApiKeyEventappend-only 的 key 管理審計(jì)記錄 created / rotated / revoked / membership_revoked且從不含完整密鑰材料——輪換、吊銷都有痕。CallRecord.refused_by凡是 treg 主動(dòng)拒絕的調(diào)用ACL 拒絕、deny 規(guī)則、密鑰失效都標(biāo)refused_by。大量refused_by就是攻擊探測(cè)的信號(hào)比正常調(diào)用日志值錢得多。refresh token 重用檢測(cè)application/auth.py已輪換的 refresh token 被再次使用會(huì)吊銷整條 grant family并記oauth.refresh_reuse審計(jì)行——這是倉(cāng)庫(kù)內(nèi)置的憑據(jù)被復(fù)制檢測(cè)器看到它基本等于有人在偷用你的授權(quán)。另一個(gè)盲區(qū)在本地 run 授權(quán)treg run --local的 grant 是唯一被允許把密鑰值交給客戶端的路徑api.py但它有兩道閘——local_run_enabled成員開(kāi)關(guān) 共享密鑰必須通過(guò)持有X-Treg-Run-Proof的隔離 runner。審計(jì)里對(duì)應(yīng)GRANT/DENY事件。自托管時(shí)如果開(kāi)了--server運(yùn)行run_allowed_bins允許列表務(wù)必盯RunRecord的argv它是服務(wù)器以服務(wù)賬號(hào)執(zhí)行了哪些命令的唯一記錄。四、自托管安全自檢清單基于以上源碼證據(jù)給一份能直接照著執(zhí)行的清單。按會(huì)導(dǎo)致裸奔的嚴(yán)重程度排序第一優(yōu)先密鑰與加密用python -m treg keygen生成TREG_SECRET_KEY寫入.env并chmod 600不要進(jìn) shell history、不要進(jìn)代碼倉(cāng)庫(kù)。非 SQLite 數(shù)據(jù)庫(kù)未設(shè)密鑰會(huì)拒絕啟動(dòng)——請(qǐng)把這條當(dāng)成部署回歸測(cè)試跑一遍故意去掉變量確認(rèn)它拒絕。顯式設(shè)置獨(dú)立的session_secret不要讓它回退到secret_keyconfig.py 第 601 行附近。主密鑰不可輪換備份到密碼管理器/KMS一旦疑似泄露按全量重新錄入供應(yīng)商憑據(jù) 輪換全部調(diào)用方 token處理。調(diào)用方 token 只存哈?？吹絫reg_明文出現(xiàn)在任何日志/備份里即為事故。第二優(yōu)先角色與 ACL按能注冊(cè)才 member、只調(diào)用就 viewer分派角色invite 時(shí)就釘好tool_access/project_access不留先進(jìn)來(lái)后收權(quán)的窗口。給協(xié)作方和 Agent 用member/專用 key 工具白名單 項(xiàng)目白名單 每日調(diào)用上限四件套而不是簡(jiǎn)單發(fā) owner/admin。記住 owner 豁免所有 ACL_tool_allowed對(duì) owner 恒真——owner 名額是團(tuán)隊(duì)內(nèi)最敏感的權(quán)限。Agent 用機(jī)器身份agents.treg.local域 token永遠(yuǎn)別給機(jī)器身份發(fā)能建 org的權(quán)限。檢查require_superadmin依賴的TREG_ADMIN_TOKENconfig.py 注釋it sees ALL orgs——這個(gè) env 兜底如果設(shè)得短或泄露等于跨租戶 admin 全開(kāi)。默認(rèn)留空、靠is_superadmin用戶是更穩(wěn)的姿勢(shì)。第三優(yōu)先審計(jì)與運(yùn)行審計(jì)是盡力而為且會(huì)在背壓時(shí)丟行把 treg 進(jìn)程的ERROR日志接進(jìn)監(jiān)控audit back-pressure出現(xiàn)即擴(kuò)容或排查。定期掃CallRecord.refused_by非空的行、oauth.refresh_reuse審計(jì)事件、ApiKeyEvent的 revoked/rotated 記錄。若啟用treg run --server嚴(yán)格維護(hù)run_allowed_bins白名單默認(rèn)不允許任意二進(jìn)制注釋明確a member cant namebash/pythonand run arbitrary code as the server user。檢查.env里TREG_BLOCKED_EMAIL_DOMAINS、TREG_PAUSED_PROVIDERS、webhook 目標(biāo)是否按需配置——這些默認(rèn)都是不攔/不暫停/不告警的安全面配置。最后一條紀(jì)律treg 的 selfhost.sh 里那句話值得反復(fù)讀——Never point TREG_PUBLIC_URL at a public domain while TREG_SINGLE_USER is true: the no-login dashboard refuses to run anywhere but loopback sqlite。單用戶免登錄模式是被代碼強(qiáng)制鎖在 loopback 的你只要把TREG_SINGLE_USERtrue的實(shí)例暴露到公網(wǎng)域名就等于親手拆掉認(rèn)證。配錯(cuò)一步照樣裸奔的每一個(gè)字都對(duì)應(yīng)上面某一條默認(rèn)值或某個(gè)我以為沒(méi)關(guān)系的開(kāi)關(guān)。把這四組檢查放進(jìn)部署流水線treg 的密鑰永不出服務(wù)器才真正成立。【免費(fèi)下載鏈接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn項(xiàng)目地址: https://gitcode.com/GitHub_Trending/treg/treg創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 自托管Treg的密鑰暗礁：Fernet加密、ACL與四級(jí)角色，配錯(cuò)一步照樣裸奔
自托管Treg的密鑰暗礁Fernet加密、ACL與四級(jí)角色配錯(cuò)一步照樣裸奔【免費(fèi)下載鏈接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn項(xiàng)目地址: https://gitcode.com/GitHub_Trending/treg/treg把 3000 個(gè)外部 API 端點(diǎn)收斂到一個(gè)網(wǎng)關(guān)、把幾十家供應(yīng)商的密鑰托管在服務(wù)器上——treg 這套OpenRouter for agent tools的設(shè)計(jì)聽(tīng)起來(lái)很美Agent 只需一個(gè) token就能替你調(diào)用 SEO、社媒、廣告、數(shù)據(jù)富集等真實(shí)世界的工具密鑰永不出服務(wù)器。但密鑰不出服務(wù)器有個(gè)前提服務(wù)器上那一坨加密落盤的密鑰以及決定誰(shuí)能用它們的那套權(quán)限必須配得對(duì)。社區(qū)里流傳的各種 treg 教程大多停留在怎么把一個(gè) token 調(diào)通的層面真正讓自托管實(shí)例裸奔的往往是四件事Fernet 主密鑰沒(méi)設(shè)或丟了、角色權(quán)限給了寬、審計(jì)日志根本沒(méi)被當(dāng)成安全數(shù)據(jù)看、以及部署時(shí)踩了那些默認(rèn)值暗坑。這篇基于 treg 倉(cāng)庫(kù)源碼逐一拆解最后給一份可以直接照著執(zhí)行的自檢清單。一、Fernet 主密鑰全庫(kù)密鑰的總開(kāi)關(guān)treg 落盤加密選的是 Fernet——對(duì)稱加密一個(gè) 32 字節(jié) urlsafe base64 主密鑰加密所有 Secret 值?？?crypto.py 的實(shí)現(xiàn)整個(gè)模塊只有幾十行def _fernet() - Fernet: key get_settings().secret_key return Fernet(key.encode() if key else _EPHEMERAL) def encrypt(plaintext: str) - str: return _fernet().encrypt(plaintext.encode()).decode() def new_key() - str: return Fernet.generate_key().decode()關(guān)鍵就在_fernet()里那個(gè)兜底secret_key為空時(shí)進(jìn)程會(huì)現(xiàn)場(chǎng)鑄一把臨時(shí)密鑰_EPHEMERAL。這意味著什么沒(méi)配TREG_SECRET_KEY的服務(wù)照樣能跑、密鑰照樣加密落盤——但重啟后所有密文都無(wú)法解密。這不是悄悄丟失而是一個(gè)響亮的安全信號(hào)代碼注釋原話是secrets wont survive a restart, which is the intended loud signal to set TREG_SECRET_KEY。更狠的防線在 infra/db.py 的verify_db()if not settings.secret_key and sqlite not in settings.database_url: raise RuntimeError( TREG_SECRET_KEY is not set on a non-SQLite database - stored secrets would be lost on the next restart. Set a key (treg keygen) before starting. )也就是說(shuō)SQLite 本地模式允許臨時(shí)密鑰反正數(shù)據(jù)在本機(jī)、丟了重連即可但只要你不是 SQLite啟動(dòng)直接拒絕。這個(gè)設(shè)計(jì)堵住了拿 Postgres 當(dāng)生產(chǎn)庫(kù)卻不設(shè)密鑰的最蠢路徑。生成與保存密鑰的正確姿勢(shì)倉(cāng)庫(kù)自己給的 self-host 腳本寫得很標(biāo)準(zhǔn)見(jiàn) selfhost.shKEY$($VENV/bin/python -m treg keygen) cat $ENV_FILE EOF TREG_SECRET_KEY$KEY EOF chmod 600 $ENV_FILEpython -m treg keygen見(jiàn)main.py就是new_key()的 CLI 出口.env權(quán)限收成 600。這套流程值得照抄因?yàn)榇蟛糠肿酝泄苁鹿是∏》粗鴣?lái)密鑰明文進(jìn) shell history、.env 權(quán)限 644、或者干脆沒(méi)設(shè)。輪換主密鑰輪換其實(shí)無(wú)解所以要在鑰匙環(huán)里做文章必須直說(shuō)一個(gè)殘酷事實(shí)treg 的 Fernet 主密鑰不支持原地輪換。encrypt()與decrypt()用的是同一個(gè)TREG_SECRET_KEY一旦換新密鑰舊密文全部解不開(kāi)唯一的補(bǔ)救是重新錄入/重連所有供應(yīng)商密鑰。倉(cāng)庫(kù)文檔auth-secrets.md和代碼都沒(méi)有提供雙密鑰滾動(dòng)解密的能力。所以對(duì)自托管者而言密鑰輪換的現(xiàn)實(shí)答案分兩層主密鑰層面能做的只有用 KMS/密鑰管理服務(wù)注入環(huán)境變量 文件權(quán)限 600 備份到密碼管理器把TREG_SECRET_KEY當(dāng)根 CA 私鑰一樣對(duì)待。丟了它 丟了一庫(kù)供應(yīng)商憑據(jù)。真正的輪換粒度在 API Key 層面treg 把誰(shuí)調(diào)用的憑據(jù)treg_xxx開(kāi)頭的 token和調(diào)用什么的供應(yīng)商憑據(jù)分開(kāi)管理。調(diào)用方 token 只存 SHA-256 哈希hash_token()見(jiàn) crypto.py庫(kù)中永遠(yuǎn)沒(méi)有明文 token輪換走rotate_agent_key/rotate_human_keyapi_keys.py用條件 UPDATE 做跨進(jìn)程原子占鎖result await db.execute( update(ApiKey).where( ApiKey.id old.id, ApiKey.state.in_((ACTIVE, DISABLED)), ApiKey.replacement_key_id.is_(None), ).values(stateREVOKED, revoked_atnow, deleted_atnow) ) if result.rowcount ! 1: raise RotationConflict舊行置為REVOKED并掛replacement_key_id舊 token 當(dāng)場(chǎng)失效同時(shí)保留審計(jì)痕跡。對(duì)Default key每名成員每團(tuán)隊(duì)一張的簽名 token輪換走default_generation自增rotate_default_generationtoken 里簽的kgclaim 對(duì)不上就直接 401revoked key。教訓(xùn)把輪換的預(yù)期放在調(diào)用方 token 上而不是主密鑰上。主密鑰設(shè)計(jì)成不可輪換意味著你必須保證它從一開(kāi)始就不會(huì)泄露——這比能輪換更考驗(yàn)部署紀(jì)律。另外注意 config.py 里一個(gè)極易被忽略的細(xì)節(jié)session_secret簽名會(huì)話 cookie 的 HMAC 密鑰未設(shè)置時(shí)回退到secret_key。也就是說(shuō)如果你只設(shè)了一個(gè)強(qiáng)secret_key而session_secret為空那么拿到secret_key的人同時(shí)能偽造會(huì)話 cookie——密鑰隔離形同虛設(shè)。生產(chǎn)環(huán)境兩個(gè)都應(yīng)顯式設(shè)置成不同的隨機(jī)值。二、四級(jí)角色與 ACL最危險(xiǎn)的權(quán)限不是給了 admintreg 的角色模型是四級(jí)owner admin member viewer定義在 models.pyROLE_RANK {viewer: 0, member: 1, admin: 2, owner: 3}角色的分界點(diǎn)在哪里看 access.py 的_require_can_registerdef _require_can_register(caller: Caller) - None: if not _role_at_least(caller.role, member): raise HTTPException(status_code403, detailviewers can call and read, but cannot register)一句話概括viewer 能調(diào)用、能讀但什么都不能注冊(cè)不能建 Secret、不能注冊(cè)工具、不能發(fā)起 OAuth。routers/api_keys.py里 viewer 連創(chuàng)建附加 key都被拒絕viewers cannot create additional keys。invite 的--role可選值也只有viewer/member/admincli.pyowner 只能通過(guò)改角色接口授予。兩個(gè)最容易被誤解的坑坑一owner 不受任何 ACL 限制而 deny 規(guī)則連 owner 都攔?？?access.pydef _tool_allowed(caller: Caller, tool_name: str) - bool: if caller.role owner: return True access caller.membership.tool_access return access is None or tool_name in accessowner 在工具級(jí) ACL 和項(xiàng)目級(jí) ACL_project_allowed面前一律放行——這是刻意的owner is never restricted但意味著把一個(gè)人升成 owner就等于把團(tuán)隊(duì)所有密鑰的使用權(quán)都交給他。反過(guò)來(lái)enforce_deny的注釋寫得明明白白deny 規(guī)則對(duì)包括 owner 在內(nèi)的所有角色生效因?yàn)閐eny rule is a guardrail, not a permission tier。坑二四級(jí)角色只是注冊(cè)權(quán)限的標(biāo)尺真正的精細(xì)管控在 Membership 行上。每個(gè)成員有一行Membershipmodels.py上面可以單獨(dú)釘三樣?xùn)|西tool_accessNULL 團(tuán)隊(duì)全部工具JSON 列表 只允許列出的工具project_accessNULL 整個(gè) orgJSON 列表 只允許這些項(xiàng)目里的工具daily_call_cap每人每日調(diào)用上限-1 不限配合local_run_enabled控制能否走本地 run 授權(quán)。兩把 ACL 鎖的關(guān)系是AND 組合_tool_usable_tool_allowed且_project_allowed。換句話說(shuō)最小權(quán)限的正確姿勢(shì)不是給 viewer 還是 member而是給協(xié)作方 member 角色 tool_access釘?shù)絺€(gè)別工具 project_access釘?shù)絾蝹€(gè)項(xiàng)目 daily_call_cap設(shè)上限。四級(jí)角色管能不能注冊(cè)ACL 管能用哪些缺一不可。還有一個(gè)隱蔽的坑invite 接口models.py 的Invite在tool_access字段上就能預(yù)置 ACL——發(fā)邀請(qǐng)時(shí)就釘好工具名單而不是等人進(jìn)來(lái)再逐項(xiàng)改。自托管團(tuán)隊(duì)如果靠先發(fā) member 邀請(qǐng)、事后收權(quán)邀請(qǐng)窗口期就是權(quán)限敞口。別忽視機(jī)器身份這條暗線treg 里 Agent 是不可登錄的機(jī)器身份郵箱掛在agents.treg.local這種不可路由域上access.py任何登錄門都解析不到它而它作為 User 卻能繼承 Membership 的所有能力。require_identity里專門防了一手if user is not None and _is_machine_email(user.email): raise HTTPException(status_code403, detail( this token belongs to a machine identity — it can call this teams tools, but cannot act as a user))機(jī)器 token 不能建 org、不能收邀請(qǐng)——因?yàn)闄C(jī)器能建 org 就自動(dòng)成為 ownerowner 又豁免所有 ACL。這是倉(cāng)庫(kù)里自己寫明的逃逸路徑自托管時(shí)給 Agent 發(fā) key 也請(qǐng)遵循同樣的最小權(quán)限專用 token、釘死的tool_access、獨(dú)立的daily_call_cap。三、審計(jì)日志的盲區(qū)它是盡力而為的不是證據(jù)鏈如果你把CallRecordmodels.py當(dāng)誰(shuí)在什么時(shí)候調(diào)了什么的完整賬本那就踩進(jìn)最大的盲區(qū)了。審計(jì)子系統(tǒng)audit.py的設(shè)計(jì)哲學(xué)模塊 docstring 第一句就是Audit writes — deferred and fire-and-forget (rule #2: never block the proxied response).具體機(jī)制是單進(jìn)程單 writer、批量落庫(kù)、后臺(tái)連接池以及背壓丟行_MAX_PENDING 5000 # shed load past this: drop the audit row rather than grow unbounded _BATCH 200隊(duì)列超過(guò) 5000 條就直接丟審計(jì)行只記一個(gè)遞增計(jì)數(shù)器并打日志。這是刻意的取舍——audit is best-effort; never OOM or wedge the server for it。所以審計(jì)表可能缺行。峰值流量下丟的正是最需要查的那幾筆。做安全復(fù)盤時(shí)不能把審計(jì)表里沒(méi)有當(dāng)成沒(méi)發(fā)生。審計(jì)與計(jì)費(fèi)分離。CallRecord注釋明確錢在 ledger 里同步落地審計(jì)表是允許丟行的分析數(shù)據(jù)the money landed in the ledger synchronously... losing a row here costs analytics, not accounting。查成本走 ledger查行為走 audit兩套數(shù)據(jù)源對(duì)不齊時(shí)別慌。失敗靜默但有 ERROR 日志。寫庫(kù)失敗不會(huì)打斷調(diào)用an audit hiccup must never break a real call但會(huì)打ERROR級(jí)日志。運(yùn)維上必須把 treg 的 ERROR 日志當(dāng)警報(bào)接住——正常流量下 audit writer 不該報(bào)錯(cuò)一旦出現(xiàn)說(shuō)明審計(jì)鏈路已破。對(duì)安全審計(jì)而言更值得盯的三張表/字段ApiKeyEventappend-only 的 key 管理審計(jì)記錄 created / rotated / revoked / membership_revoked且從不含完整密鑰材料——輪換、吊銷都有痕。CallRecord.refused_by凡是 treg 主動(dòng)拒絕的調(diào)用ACL 拒絕、deny 規(guī)則、密鑰失效都標(biāo)refused_by。大量refused_by就是攻擊探測(cè)的信號(hào)比正常調(diào)用日志值錢得多。refresh token 重用檢測(cè)application/auth.py已輪換的 refresh token 被再次使用會(huì)吊銷整條 grant family并記oauth.refresh_reuse審計(jì)行——這是倉(cāng)庫(kù)內(nèi)置的憑據(jù)被復(fù)制檢測(cè)器看到它基本等于有人在偷用你的授權(quán)。另一個(gè)盲區(qū)在本地 run 授權(quán)treg run --local的 grant 是唯一被允許把密鑰值交給客戶端的路徑api.py但它有兩道閘——local_run_enabled成員開(kāi)關(guān) 共享密鑰必須通過(guò)持有X-Treg-Run-Proof的隔離 runner。審計(jì)里對(duì)應(yīng)GRANT/DENY事件。自托管時(shí)如果開(kāi)了--server運(yùn)行run_allowed_bins允許列表務(wù)必盯RunRecord的argv它是服務(wù)器以服務(wù)賬號(hào)執(zhí)行了哪些命令的唯一記錄。四、自托管安全自檢清單基于以上源碼證據(jù)給一份能直接照著執(zhí)行的清單。按會(huì)導(dǎo)致裸奔的嚴(yán)重程度排序第一優(yōu)先密鑰與加密用python -m treg keygen生成TREG_SECRET_KEY寫入.env并chmod 600不要進(jìn) shell history、不要進(jìn)代碼倉(cāng)庫(kù)。非 SQLite 數(shù)據(jù)庫(kù)未設(shè)密鑰會(huì)拒絕啟動(dòng)——請(qǐng)把這條當(dāng)成部署回歸測(cè)試跑一遍故意去掉變量確認(rèn)它拒絕。顯式設(shè)置獨(dú)立的session_secret不要讓它回退到secret_keyconfig.py 第 601 行附近。主密鑰不可輪換備份到密碼管理器/KMS一旦疑似泄露按全量重新錄入供應(yīng)商憑據(jù) 輪換全部調(diào)用方 token處理。調(diào)用方 token 只存哈?？吹絫reg_明文出現(xiàn)在任何日志/備份里即為事故。第二優(yōu)先角色與 ACL按能注冊(cè)才 member、只調(diào)用就 viewer分派角色invite 時(shí)就釘好tool_access/project_access不留先進(jìn)來(lái)后收權(quán)的窗口。給協(xié)作方和 Agent 用member/專用 key 工具白名單 項(xiàng)目白名單 每日調(diào)用上限四件套而不是簡(jiǎn)單發(fā) owner/admin。記住 owner 豁免所有 ACL_tool_allowed對(duì) owner 恒真——owner 名額是團(tuán)隊(duì)內(nèi)最敏感的權(quán)限。Agent 用機(jī)器身份agents.treg.local域 token永遠(yuǎn)別給機(jī)器身份發(fā)能建 org的權(quán)限。檢查require_superadmin依賴的TREG_ADMIN_TOKENconfig.py 注釋it sees ALL orgs——這個(gè) env 兜底如果設(shè)得短或泄露等于跨租戶 admin 全開(kāi)。默認(rèn)留空、靠is_superadmin用戶是更穩(wěn)的姿勢(shì)。第三優(yōu)先審計(jì)與運(yùn)行審計(jì)是盡力而為且會(huì)在背壓時(shí)丟行把 treg 進(jìn)程的ERROR日志接進(jìn)監(jiān)控audit back-pressure出現(xiàn)即擴(kuò)容或排查。定期掃CallRecord.refused_by非空的行、oauth.refresh_reuse審計(jì)事件、ApiKeyEvent的 revoked/rotated 記錄。若啟用treg run --server嚴(yán)格維護(hù)run_allowed_bins白名單默認(rèn)不允許任意二進(jìn)制注釋明確a member cant namebash/pythonand run arbitrary code as the server user。檢查.env里TREG_BLOCKED_EMAIL_DOMAINS、TREG_PAUSED_PROVIDERS、webhook 目標(biāo)是否按需配置——這些默認(rèn)都是不攔/不暫停/不告警的安全面配置。最后一條紀(jì)律treg 的 selfhost.sh 里那句話值得反復(fù)讀——Never point TREG_PUBLIC_URL at a public domain while TREG_SINGLE_USER is true: the no-login dashboard refuses to run anywhere but loopback sqlite。單用戶免登錄模式是被代碼強(qiáng)制鎖在 loopback 的你只要把TREG_SINGLE_USERtrue的實(shí)例暴露到公網(wǎng)域名就等于親手拆掉認(rèn)證。配錯(cuò)一步照樣裸奔的每一個(gè)字都對(duì)應(yīng)上面某一條默認(rèn)值或某個(gè)我以為沒(méi)關(guān)系的開(kāi)關(guān)。把這四組檢查放進(jìn)部署流水線treg 的密鑰永不出服務(wù)器才真正成立。【免費(fèi)下載鏈接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn項(xiàng)目地址: https://gitcode.com/GitHub_Trending/treg/treg創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考