OSCache (OpenSymphony Cache) 是輕量級、高效能的 Java 緩存框架，支援記憶體/磁碟緩存、集群同步、緩存過期策略等豐富特性。配置檔 oscache.properties 放置於 WEB-INF/classes/，掌握核心屬性可精準控制緩存行為。本文基於官方文檔與實戰經驗，逐項解析關鍵配置。
| 屬性 | 預設值 | 說明 | 建議 |
|---|---|---|---|
| cache.memory | true | 啟用記憶體緩存。設為 false 可純磁碟模式，但效能大幅下降 | 生產環境保持 true |
| cache.capacity | 無限制 (-1) | 記憶體緩存最大條目數。超過時觸發淘汰算法。負數表無限制 | 根據堆記憶體設定，如 10000，防止 OOM |
| cache.algorithm | LRUCache (設定 capacity 時) | 淘汰算法： • LRUCache - 最近最少使用 • FIFOCache - 先進先出 • UnlimitedCache - 不淘汰 (capacity 未設定時預設) | LRUCache 通用最優 |
| 屬性 | 預設值 | 說明 | 建議 |
|---|---|---|---|
| cache.blocking | false | true: 緩存未命中時阻塞其他線程，等待重建完成 false: 返回舊內容(若有)，背景異步重建 | 強一致性場景設 true；高併發讀多寫少設 false 提升吞吐 |
| cache.persistence.overflow.only | false (2.1+) | true: 僅當記憶體緩存滿時才持久化到磁碟 false: 所有緩存條目同步持久化 | 記憶體充足設 true，減少磁碟 I/O |
| 屬性 | 預設值 | 說明 |
|---|---|---|
| cache.unlimited.disk | false | false 時磁碟緩存容量 = cache.capacity；true 時磁碟無限制 |
| cache.persistence.class | 無 | 持久化實現類，必須實現 PersistenceListener。內建：• com.opensymphony.oscache.plugins.diskpersistence.HashDiskPersistenceListener (哈希檔名，推薦)• com.opensymphony.oscache.plugins.diskpersistence.DiskPersistenceListener (可讀檔名，可能遇非法字符) |
| cache.path | 無 | 磁碟緩存存儲目錄絕對路徑。 Windows: c:\\myapp\\cache (雙反斜杠轉義)Linux: /opt/myapp/cache需確保進程有讀寫權限 |
| 屬性 | 預設值 | 說明 |
|---|---|---|
| cache.key | __oscache_cache | ServletContext/Session 域中緩存對象的鍵名。程式碼可用 Const.DEFAULT_CACHE_KEY 獲取 |
| cache.use.host.domain.in.key | false | true 時自動在緩存鍵加入主機名，支援同一應用部署多虛擬主機隔離 |
cache.event.listeners 逗號分隔的類名列表，實現 CacheEntryEventListener (增刪改清) 或 CacheMapAccessEventListener (命中/未命中統計)。內建實現：
com.opensymphony.oscache.plugins.clustersupport.BroadcastingCacheEventListener — 集群廣播失效事件 (需配合 JGroups)com.opensymphony.oscache.extra.CacheEntryEventListenerImpl — 生命週期事件計數器com.opensymphony.oscache.extra.CacheMapAccessEventListenerImpl — 訪問統計 (命中率分析)| 屬性 | 預設值 | 說明 |
|---|---|---|
| cache.cluster.multicast.ip | 231.12.21.132 | 組播 IP，集群節點發現用 |
| cache.cluster.properties | UDP(mcast_addr=231.12.21.132;mcast_port=45566;...) | JGroups 協議棧完整配置字符串。生產環境需根據網絡拓撲調整 mcast_addr、bind_addr、port 等，避免跨網段干擾 |
注意： 集群模式下所有節點 cache.cluster.properties 必須完全一致，且網絡允許組播/單播通訊。
# 基礎開關
cache.memory=true
cache.capacity=20000
cache.algorithm=com.opensymphony.oscache.base.algorithm.LRUCache
# 併發策略
cache.blocking=true
cache.persistence.overflow.only=true
# 磁碟持久化
cache.unlimited.disk=false
cache.persistence.class=com.opensymphony.oscache.plugins.diskpersistence.HashDiskPersistenceListener
cache.path=/var/cache/oscache
# 鍵隔離
cache.key=myapp_cache
cache.use.host.domain.in.key=true
# 監控統計
cache.event.listeners=com.opensymphony.oscache.extra.CacheMapAccessEventListenerImpl
# 集群 (如需)
# cache.cluster.multicast.ip=239.255.0.1
# cache.cluster.properties=UDP(mcast_addr=239.255.0.1;mcast_port=45566;bind_addr=192.168.1.100):PING:MERGE2:FD_SOCK:VERIFY_SUSPECT:pbcast.NAKACK:UNICAST:pbcast.STABLE:FRAG:pbcast.GMS-Xmx 估算單條目大小，預留 30% 堆給業務對象cache.pathOSCache 雖非主流新選擇 (Ehcache、Caffeine、Redis 更常用)，但在存量系統中仍具價值。理解其配置機制有助於平滑遷移或維護現有緩存層。核心原則：容量有界、策略顯式、持久化可控、監覽可視。
