> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Zotero 整合

> 讓使用者在 Kubernetes 部署中，從其 Zotero 文獻庫匯入 .bib 檔案。

Zotero 匯入在每個 Ayakaleaf Pro Pod 的 **web** 服務（`tpr-webmodule` 模組）中執行。請依照 [Zotero 整合](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/integrations/zotero-integration.md)註冊 Zotero OAuth 用戶端，並將回呼 URL 設為 `${OVERLEAF_SITE_URL}/user/zotero/oauth/callback`，然後依下列方式設定 Kubernetes。

| | |
| - | - |
| 服務 | web，位於每個 Ayakaleaf Pro Pod 中；於 web 啟動時讀取 |
| Pod → Zotero | 當使用者連結 Zotero 或匯入、重新整理檔案時，連線至 `https://www.zotero.org/oauth/*` 與 `https://api.zotero.org` |
| 瀏覽器 → Zotero | 前往 `https://www.zotero.org/oauth/authorize`，再返回回呼 URL |
| Zotero → Overleaf | 無：執行個體不需要能從網際網路連線 |
| 儲存的資料 | 使用者的 Zotero 金鑰，經加密後儲存在 MongoDB 中 |
| 定期工作 | 無：只有在使用者要求時才會重新整理檔案 |

### 設定

**1. ConfigMap**

```yaml title="30-config.yaml (changes)" theme={null}
  ENABLED_LINKED_FILE_TYPES: project_file,project_output_file,url,zotero
  ZOTERO_CLIENT_ID: <client key>
  # optional: send the module's requests to Zotero through an HTTP proxy
  # ZOTERO_PROXY_URL: http://proxy.example.com:3128
```

`ENABLED_LINKED_FILE_TYPES` 會取代安裝時的值；請保留您現有的類型並加入 `zotero`（若兩者都使用，也請加入 `mendeley`）。

**2. Secret**

```bash theme={null}
kubectl -n overleaf patch secret overleaf-secrets --type merge -p '{"stringData":{
  "ZOTERO_CLIENT_SECRET":"<client secret>",
  "ZOTERO_CIPHER_PASSWORD":"'"$(openssl rand -hex 32)"'"}}'
```

`ZOTERO_CIPHER_PASSWORD` 用於加密儲存在 MongoDB 中的使用者 Zotero 金鑰。若未設定，每個 Pod 會在自己的 `/var/lib/overleaf/data` 中產生金鑰檔案。在[多個副本](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/kubernetes/horizontal-scaling.md)的情況下，每個節點的金鑰都不同，由其他副本服務的使用者將無法使用其已連結的 Zotero 帳號。請在第一位使用者連結 Zotero 之前設定：之後若變更，所有使用者都必須重新連結 Zotero。

**3. 套用並重新啟動**

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
```

### 多個副本

請在 Secret 中設定 `ZOTERO_CIPHER_PASSWORD`，詳見上文。若未設定，在某個副本上匯入的檔案將無法在另一個副本上重新整理：重新整理會失敗並顯示「The remote service produced an error」，因為該副本的金鑰檔案無法解密使用者的 Zotero 金鑰。在 Secret 中設定密碼後，所有副本都能正常運作；我們在 `overleaf-0` 上匯入並在 `overleaf-1` 上重新整理，測試了這兩種情況。OAuth 交握將其狀態保存在 Redis 的工作階段中，因此回呼可以抵達任何副本。

### 在 Kubernetes 上的測試

我們以模擬的 [www.zotero.org](http://www.zotero.org) 與 api.zotero.org（透過來自 `overleaf-certs` 的 `NODE_EXTRA_CA_CERTS` 信任），在 Kubernetes 1.37 上以三個副本置於 HAProxy 之後進行測試，Zotero 的端對端測試全數通過（18 個案例）：透過 OAuth 1.0a 連結與解除連結、將文獻庫與群組匯入 `.bib` 檔案、重新整理該檔案、在 Zotero 上撤銷金鑰、要求重新連結、協作者可搜尋參考文獻、只有匯入者可以重新整理、API 錯誤，以及與 Zotero 之間的緩慢連線。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.