HCL Domino REST API 完全安裝指南：從下載、配置到 AI 整合 (2025 最新版)

HCL Domino REST API（原名 Project Keep）是現代化 Domino 應用程式的核心關鍵。它提供了一套標準的 JSON/HTTP 介面，支援 Swagger UI、OAuth2 授權，更是將 Domino 資料庫與現代 AI 平台（如 OpenAI, Azure AI）整合的最佳橋樑。

本文根據 HCL 官方文件 (2025) 進行校正，提供從零開始的安裝、配置、排錯到 API 測試的完整教學，適用於 Windows 與 Linux 生產環境。

1. 前置條件與環境檢查

在開始之前，請確保您的伺服器滿足以下要求：

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

Java 執行路徑 (重要)： 在安裝步驟中，直接輸入 java -jar 經常會失敗，因為伺服器作業系統通常沒有安裝全域 Java，或者版本不對。正確做法是呼叫 Domino 目錄下的 JVM。

1. 檔案權限 (Linux)： Linux 環境下安裝，通常需要注意檔案擁有者 (User/Group) 必須是 notes:notes，否則啟動會報錯。
2. Scope 與 Schema 概念： Domino REST API 與傳統 Domino Access Services 不同，預設不會開放所有 NSF。雖然安裝後測試可以通，但在實務上通常建議提到需在 Admin UI 設定 Scope (範圍)。

2. 下載安裝程式

請前往 HCL My Software Portal (FlexNet) 下載對應版本的安裝包。

搜尋關鍵字：Domino REST API。

你會下載到類似以下的檔案（版號可能會更新）：

Domino_REST_API_V1.1.x_R14_Installer.tar.gz (適用於 R14)

Domino_REST_API_V1.1.x_R12_Installer.tar.gz (適用於 R12

解壓縮後，您會看到核心安裝檔：restapiInstall.jar。

3. 安裝 REST API (Windows / Linux)

⚠️ 關鍵技巧： 執行安裝時，建議使用 Domino 內建的 Java 來執行 .jar 檔，以確保相容性並避免「找不到 Java」的錯誤。

🔧 Windows 安裝範例

假設 Domino 安裝在 C:\Program Files\HCL\Domino：

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 安裝範例

假設 Domino 安裝在 /opt/hcl/domino，請使用 root 或 sudo 執行：

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：自動將 restapi 加入 notes.ini 的 ServerTasks 中，讓它隨 Domino 自動啟動。
• Linux 注意事項： 安裝完成後，請務必檢查 /opt/hcl/domino/restapi 目錄的權限，確保擁有者是 notes:notes。 chown -R notes:notes /opt/hcl/domino/restapi

4. 確認設定檔 (Notes.ini)

安裝程式執行完畢後，請檢查 notes.ini 是否已正確更新：

ServerTasks=... ,restapi

(若您不想自動啟動，可將其移除，改用手動 load restapi)

RESTAPI_HOME：確認路徑正確。

Windows: RESTAPI_HOME=C:\Program Files\HCL\Domino\restapi

Linux: RESTAPI_HOME=/opt/hcl/domino/restapi

5. 啟動與驗證

開啟 Domino Console，輸入以下指令啟動服務：

load restapi

若啟動成功，您會看到類似以下的console訊息：

Domino REST API initialized on port 8880

瀏覽器測試

打開瀏覽器輸入：http://your-server-ip:8880 如果看到 Domino REST API 的歡迎畫面或 JSON 回應，代表服務已正常運作。

6. API 實戰：登入與讀取資料

我們使用 curl 來驗證 API 是否能正常溝通。

第一步：取得 Access 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"
}

第二步：讀取 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" }
  ]
}

7.預設 Port 與防火牆設定

資安建議： 生產環境建議僅對外開放 8880，將 8881 限制在內網存取。

8. 常見錯誤排解 (Troubleshooting)

Q1: Console 顯示 Command text not found 或無法啟動？

• 檢查 restapi 資料夾是否存在。
• 檢查 notes.ini 中的 RESTAPI_HOME 路徑是否正確（注意斜線方向）。
• Linux 用戶請檢查資料夾權限是否屬於 notes 使用者。

Q2: 回傳 401 Unauthorized？

• 確認該帳號存在於 Domino Directory (names.nsf)。
• 確認該帳號已設定 Internet Password (HTTP 密碼)。
• Domino REST API 預設依賴 Domino 的 HTTP 驗證機制。

Q3: 回傳 404 Not Found？

• 確認 URL 大小寫（部分 Linux 系統敏感）。
• 確認資料庫檔案名稱正確（包含 .nsf）。
• 進階： 某些資料庫可能需要在 Admin UI (Port 8881) 中設定 Schema 與 Scope 才能存取。

9. Python 與 AI 整合範例

Domino REST API 是將舊系統對接 AI 的最佳利器。以下是用 Python 抓取 Domino 文件並準備送給 LLM (如 ChatGPT) 的範本：

import requests
import json

# 設定參數
BASE_URL = "https://your-domino-server:8880"
DB_NAME = "mydb.nsf"
TOKEN = "你的_ACCESS_TOKEN"

# 呼叫 API
headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

try:
    response = requests.get(
        f"{BASE_URL}/api/v1/data/{DB_NAME}/Documents",
        headers=headers,
        verify=False # 開發環境可忽略 SSL 警告
    )
    
    if response.status_code == 200:
        docs = response.json().get("items", [])
        print(f"成功取得 {len(docs)} 筆文件，準備進行 AI 分析...")
        
        for doc in docs:
            # 這裡可以串接 OpenAI API
            print(f"文件標題: {doc.get('Subject')}")
    else:
        print(f"錯誤: {response.status_code} - {response.text}")

except Exception as e:
    print(f"連線失敗: {e}")

可用於：

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

10. 安全最佳實踐

1. 全面啟用 HTTPS： 即使在內網，也應配置 TLS 憑證。
2. 最小權限原則： 透過 Domino ACL 控制存取，並在 REST API Admin UI 中設定 Scope，只開放必要的欄位。
3. 使用 OAuth2 / OIDC： 在生產環境中，建議整合 Keycloak 或 Azure AD 進行身分驗證，而非使用 Basic Auth。

參考資料

• HCL Domino REST API 官方文件 (Installation)
• REST API Quickstart Guide

🧠 本文由 DreamJ AI 技術新聞生成系統 自動撰寫與優化，內容僅供技術研究與學習參考，實際環境請搭配官方公告與資安建議。