Domino REST API 上線前：安全模型、rich text 單向、CORS 與 admin port

2026.08.24 約 1,298 字

這是 DRAPI 系列的最後一篇。前五篇你已經走完：概觀、認證、scope/schema、文件 CRUD、DQL 查詢。功能都通了，但把它交給真實使用者之前，Domino 開發者心裡通常有兩個問號：

這一篇就回答這兩題。

重點摘要

不會漏：DRAPI 是分層安全——JWT（官方說「All Domino REST API access is authorized using a signed JWT claim」、且「No anonymous access is granted for REST data」）、scope（只有管理員設定過的庫才對外），而底層 Domino 的 ACL 與 Readers／Authors 欄位照算。
secure-by-default：官方明講「Databases aren’t automatically exposed on REST when you run Domino REST API. Only the ones configured by the administrators」。
rich text 是單向的：官方說 rich text 會轉成 HTML/MIME 出去，但不會把 MIME 轉回 rich text。
沒配置的欄位碰不到、item 不存在就不回傳——「absent ≠ empty」的老規矩在 REST 這端一樣成立。
上線前要收的口：CORS 設定、把 admin 用的 port（console 8889、metrics 8890、health 8886）鎖好，別跟資料 port 8880 一起裸奔。

這是 Domino 開發者對任何「把 NSF 開上網」的東西最先問、也最該問的一題。答案是：不會——只要你沒把安全自己拆掉。DRAPI 的安全是疊起來的三層：

JWT：官方說「All Domino REST API access is authorized using a signed JWT claim」，而且「No anonymous access is granted for REST data」——沒有匿名存取，每個請求都得帶一個簽章過的 token。
scope：官方明講「Databases aren’t automatically exposed on REST when you run Domino REST API. Only the ones configured by the administrators」——沒被設定的庫，REST 這端根本看不到。
Domino 自己的文件層安全：這是關鍵。你 JWT 的 sub 是一個 Domino 名稱（第二篇講過），DRAPI 就是以那個 Domino 使用者的身分去讀資料——所以那個 NSF 的 ACL、Readers／Authors 欄位一樣在算。一個只被授權看 A 群文件的使用者，透過 REST（不管是 CRUD、/lists 還是 DQL）也只拿得到 A 群；Readers 欄位擋掉的，REST 這端一樣拿不到。

換句話說，DRAPI 沒有另立一套安全去繞過 Domino，而是疊在 Domino 既有的安全模型之上。這也是為什麼前面第三篇會說「三層一起算」——scope 決定門開不開，Domino 的 ACL/Readers 決定門後面你這個人到底看得到什麼。

（站上更早那篇 RAG webinar 筆記提過一個相關教訓：Domino IQ 的 RAG 也遵守 Readers 欄位——但那個功能是到 2026 FP1 才真正修好。文件層安全「有沒有被尊重」值得你在自己的環境實測確認，不要只憑文件。）

功能通、安全也在，但有幾個限制最好在設計階段就知道，別上線才發現：

rich text 只能單向轉出。官方寫得很白：「The Domino REST API translates Rich Text to HTML/MIME. This is one way. The Domino REST API doesn’t translate MIME back to Rich Text.」——你讀一個 rich text 欄位，拿到的是 HTML/MIME；但你不能用同樣的路把 rich text 寫回去。要處理富文本的雙向編輯，這是個硬限制。
只有配置過的欄位能碰：「Only configured fields can be created, read, or updated.」沒放進 schema／KeepConfig 的欄位，就算文件上真的有，REST 這端也存取不到。
item 不存在就不回傳：「If an item doesn’t exist in a document, it doesn’t get returned.」——所以回來的 JSON 裡少了某個鍵，可能是「這份文件沒這個欄位」，不是「值是空的」。這跟 Java 那端 getItemValue 的「absent ≠ empty」是同一個老規矩。
同名 form／view 選哪個沒保證：「When you have multiple views with the same name, the Admin UI selects the first one found.」——庫裡有同名設計元件時，別假設它挑的是你以為的那個。

CORS：你的前端多半跑在別的網域，瀏覽器會擋跨來源請求。DRAPI 的 troubleshooting 把 CORS 列為存取 Admin UI／打 API 時的常見錯誤——上線前要把允許的來源設對。
鎖 admin port：資料走 8880，但 console（8889）、metrics（8890）、health check（8886）這些管理／監控 port（第二篇 functional accounts 那段提過）不該對外裸奔，正式環境要用防火牆收好。
其他運維常客：啟動時 Address already in use（port 撞了）、OutOfMemoryError（Java heap 不夠）、keepconfig.d 裡的 JSON 打錯——這些 troubleshooting 頁都列了，部署時心裡有個底。

六篇走下來，把最會踩的坑收成一張對照表：

症狀	通常是
呼叫回 401	token 過期，或 server 重啟換了簽章金鑰（第二篇）
有 token 卻被擋	你的 scope 不在 token 裡，或 Domino ACL／Readers 擋下（第三篇）
DQL 沒寫錯卻查不到	那個 form 少了 `dql` mode（第五篇）
rich text 寫不回去	那是單向轉換，設計上就不支援（本篇）
瀏覽器前端打不通	CORS 沒設對（本篇）

DRAPI 把一個 NSF 變成一組現代、標準、語言無關的 REST API——但它不是把 Domino 的安全與規矩丟掉，而是疊在上面。搞懂這六篇，你就能把手上的 NSF 乾淨、安全地開出去。系列完結。