—

作者:

分類: domino, DreamJ AI, hcl, hcl domino, Notes, 企業系統開發

Domino REST API 安裝與配置全攻略

HCL Domino REST API（原名 Project Keep）是一套以 JSON / HTTP 存取 Domino 資料庫的現代化 API，支援資料讀寫、查詢、授權 OAuth2、Swagger UI 並可與 AI 平台（OpenAI, Azure AI 等）整合。

本文依 HCL 官方文件（2025）」校正過，提供你最新、正確、可在生產環境使用的安裝步驟與排錯方式。

1. 前置條件與環境檢查

項目	說明
作業系統	Windows Server 2019 / 2022、Linux (RHEL 8/9、Ubuntu 22.04)
Domino 版本	Domino 12.0.2 FP3+、Domino 14+（建議 Domino 14.0.1 FP1 以上）
HTTPS	建議啟用，REST API 支援 TLS / Let’s Encrypt
Java	Domino 內建 OpenJDK，不需額外安裝
API Port/HTTP Port	若本機已經使用port，需調整相關設定

完成以上檢查後即可安裝 REST API.相關需求請參照原廠需求。

2. 下載 REST API 安裝包（官方來源）

前往 HCL My Software Portal 下載：

📌 Domino REST API Installer（非單純 jar 檔，而是整個安裝器）

你會看到類似以下檔案：

Domino_REST_API_V1.1.5_R14_Installer.tar.gz
Domino_REST_API_V1.1.5_R14.5_Installer.tar.gz
Domino_REST_API_V1.1.5_R12_Installer.tar.gz

解壓內容包含：

restapiInstall.jar（安裝器）
restapi 目錄（模組內容）
Docker 套件（如需要）

3. 安裝 REST API（Windows / Linux 正確語法）

✔ Windows 安裝

java -jar restapiInstall—xxx.jar ^
 -i "C:\Program Files\HCL\Domino\notes.ini" ^
 -d "C:\Program Files\HCL\Domino\Data" ^
 -p "C:\Program Files\HCL\Domino" ^
 -r "C:\Program Files\HCL\Domino\restapi" ^
 -a

如圖:(安裝範例)

Linux 安裝

sudo java -jar restapiInstall-xxx.jar \
 -i "/local/notesdata/notes.ini" \
 -d "/local/notesdata" \
 -p "/opt/hcl/domino/notes/latest/linux" \
 -r "/opt/hcl/domino/restapi" \
 -a

-a 代表自動加入到 Domino Server Tasks，安裝後 Domino 會自動設定相關參數及修改啟動參數：

#若安裝後要啟動可以在Domino console下
load restapi

4. 確認 Notes.ini 設定

安裝完成後，需確認 Notes.ini 是否包含：

ServerTasks=... ,restapi

若你安裝時使用 -n（不加入自動啟動），你必須手動加入：

ServerTasksAt1=restapi

並確保 REST API 路徑存在：

RESTAPI_HOME=/opt/hcl/domino/restapi   (Linux)
RESTAPI_HOME=C:\Program Files\HCL\Domino\restapi  (Win)

5. 啟動與測試 REST API

✔ 啟動（Domino Console）

load restapi

成功訊息會顯示：

Domino REST API initialized on port 8880

6. 使用 curl 驗證 API 登入（正確 JSON 範例）

使用 /api/v1/auth 取得 JWT Token：

curl --location --request POST "https://yourserver:8880/api/v1/auth" \
--header "Content-Type: application/json" \
--data '{
  "username": "myuser",
  "password": "mypassword"
}'

成功回應：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "Bearer"
}

7. 讀取 Domino 資料庫文件

假設資料庫：mydb.nsf

curl -X GET "https://yourserver:8880/api/v1/data/mydb.nsf/Documents" \
-H "Authorization: Bearer <token>"

正確回傳：

{
  "items": [
    { "@id": "OF453A1", "Subject": "測試文件" },
    { "@id": "OF88B91", "Subject": "測試文件2" }
  ]
}

REST API 預設 Port 一覽

Port	用途
8880	REST API Gateway
8881	Admin UI / Dashboard
8882	Metrics（Prometheus）
8883	Health Check

9. 常見問題與排解

❌ API 無法啟動

✔ 檢查：
RESTAPI_HOME
restapi 目錄是否存在
notes.ini 裡是否有 ServerTasks=…,restapi
❌ 401 Unauthorized

✔ 帳號必須：

在 Domino Directory 存在
已啟用網路密碼（HTTP Password）

❌ OAuth2 無法運作

需設定：
IdPCONFIG / OAuth Provider / JWT Config
Domino REST API 預設使用 Basic / JWT，未配置 OAuth2 不會自動啟用。

❌ 404 Not Found

DB 名稱錯誤（必須輸入正確 .nsf）

API 路徑必須是 /api/v1/data/...

10. 與 AI / 雲端整合（正確格式）

你可以用 Python 將文件送到 OpenAI：

import requests

resp = requests.get(
    "https://server:8880/api/v1/data/mydb.nsf/Documents",
    headers={"Authorization": f"Bearer {TOKEN}"},
    verify=False
)

docs = resp.json()["items"]

for d in docs:
    print("文件標題：", d.get("Subject"))

可用於：

自動摘要
自動分類
文件產生內容（如 AI 回覆/標記）

11. 安全最佳實踐

✔ 全站 HTTPS + TLS 1.3
✔ 設定最小權限（Domino ACL / Reader / Author）
✔ 啟動 API Audit 日誌
✔ 每月更新 Domino + REST API
✔ 搭配反向代理（Nginx/Apache）與 WAF