Nextcloud客製化網頁：插入外部JavaScript腳本 / Nextcloud Customized Webpage: Inserting External JavaScript Scripts
要大幅度修改Nextcloud的網頁的話，建立主題(theme)可能是最常見的建議。但如果我們是要在Nextcloud的網頁裡面插入外部JavaScript腳本的話，這手續可就麻煩得多了。讓我們應用調整Docker的Nextcloud的技巧，在Nextcloud安裝完後，自動佈署修改後的程式碼吧。
If you want to drastically modify the Nextcloud web interface, creating a theme is probably the most common suggestion. However, if you want to insert external JavaScript scripts into the Nextcloud web pages, the procedure becomes much more complicated. Let's apply the techniques of customizing a Dockerized Nextcloud instance to automatically deploy modified code after Nextcloud is installed.
Nextcloud程式碼的位置 / Location of Nextcloud Code
https://hub.docker.com/_/nextcloud/
在Nextcloud的Docker版本裡面，Nextcloud的程式碼被擺在「 /var/www/html 」裡面。而影響Nextcloud顯示外觀的程式碼則擺在更深一層的「 /var/www/html/core/templates/ 」裡面。
https://www.schillmania.com/projects/snowstorm/
我們要客製化什麼功能呢？這邊舉的例子是scottschiller發佈的「Snowstorm」。它的程式碼可以讓網頁開始下雪。一般的做法是在網頁裡面插入以下程式碼即可：
<script src="https://cdnjs.cloudflare.com/ajax/libs/Snowstorm/20131208/snowstorm-min.js"></script>但是要在Docker的Nextcloud裡面就沒有這麼簡單了。首先，在Nextcloud安裝之前，其實「/var/www/html」並沒有任何檔案跟資料夾。如果我們用Docker的volume直接掛載，這會與Nextcloud內部的權限相互衝突，安裝會無法順利進行。解決方法是必須在安裝之後再複製修改後的腳本。
另一個問題是Nextcloud在前端網頁執行的<script>需要加上「nonce」屬性。在 HTML 和 JavaScript 中，nonce (全稱為「number used once」，即「一次性數字」)是一種 安全機制，主要用於 內容安全政策 (CSP，Content Security Policy)，以防止 跨站腳本攻擊（XSS，Cross-Site Scripting）。為了要讓，<script>能在Nextcloud裡面執行，我們需要把原始的<script>配合Nextcloud的寫法，修改成以下的樣子：
<script
nonce="<?php p($_['cspNonce']); ?>"
src="https://cdnjs.cloudflare.com/ajax/libs/Snowstorm/20131208/snowstorm-min.js"
></script>
其中「<?php p($_['cspNonce']); ?>」便是由Nextcloud自動產生的nonce。每次讀取網頁都會不一樣，但只有擁有同樣nonce的JavaScript腳本才能順利執行。
在Docker版本Nextcloud裡面客製化程式碼 / Customizing Code Within a Dockerized Nextcloud Instance
https://github.com/pulipulichen/docker-Nextcloud-demo-2025
在瞭解問題之後，我們便能開始嘗試修改Docker版本Nextcloud的程式碼。為了方便說明，我將程式碼擺放到「docker-Nextcloud-demo-2025」GitHub保存庫，供大家參考。
關鍵的修改點有三個：
1. 準備要修改的程式碼 / Preparing to Modify the Code
如果我們要讓客製化的JavaScript在登入之後才會執行，那麼我們要修改的是「 /var/www/html/core/templates/layout.user.php」。layout.user.php的原始碼可以在nextcloud/server的GitHub保存庫找到。
我們要作的事情是在layout.user.php加上需要客製化的程式碼。我把它加在</body>前面。完整程式碼可以看我在GitHub上的layout.user.php。
2. 在docker-compose.yml掛載客製化程式碼 / Mounting Custom Code in Docker-Compose.yml
接下來我們要在docker-compose.yml，把客製化程式碼的資料夾用volumnes掛載。我把客製化程式碼放在「html」資料夾底下，而Docker裡面我則是掛載到「/html」路徑。完整配置可以看我在GitHub上的docker-compose.yml。
3. Nextcloud安裝完成後複製客製化程式碼 / Copy Customized Code After Installing Nextcloud
接著我們使用「讓Docker架設的Nextcloud預設關閉或開啟應用程式」這篇的技巧，在「post-installation」裡面加上「copy_html.sh」，讓它出現在Nextcloud容器裡面的「/docker-entrypoint-hooks.d/post-installation」資料夾底下，這樣Nextcloud在初次安裝完成後便會執行裡面的程式碼。
GitHub保存庫裡面可以看到copy_html.sh的完整內容，但其實主要程式碼只有兩行：
#!/bin/bash
cp -rf /html/* /var/www/html/這個意思是在Nextcloud安裝完成後，將掛載到「/html」的客製化程式碼，全部複製到「/var/www/html/」裡面，並且直接覆蓋。
這樣我們就設定完成了。
成果 / Outcomes
如果你之前已經安裝過Nextcloud，此時我們要先移除掉Docker建立的持久性檔案集 (volume)，指令如下：
docker compose down -v接著再用啟動Nextcloud：
docker compose up
登入Nextcloud。登入的帳號密碼已經在docker-compose.yml設定了，我這裡的預設是「admin」跟「password」。
登入之後，你可以注意到Nextcloud的介面有了雪花紛飛的特效。這樣就完成囉。
結語 / Conclusion
由於Docker的設計方式，使得我們不容易修改安裝後的Nextcloud。現在借住鉤子資料夾post-installation的設計，我們得以在Nextcloud安裝完後還能修改程式碼。這篇也連帶解決了CSP安全性問題中較為常見的nonce機制。
如果你在Nextcloud安裝完成後還想要修改程式碼的話，那要如何處理呢？很簡單，鉤子資料夾還有「/docker-entrypoint-hooks.d/before-starting」這項設定，可以讓你在啟動Nextcloud之前執行。那我們就可以這篇的做法，在Nextcloud執行之前複製客製化程式碼即可。
有人可能會問，「在Nextcloud容器裡面複製到 /var/www/html 的檔案，會保存在主機的那個位置呢？」我們的設定是保存在「nextcloud:」volume裡面，而這是由Docker管理的內部保存位置。Linux裡是保存在「/var/lib/docker/」底下，但它並不是由我們在容器裡面看到的形式保存，而是用特殊的雜湊資料結構陳列。關於Docker Volume的概念可以看看flynncanfly所寫的「Day-7 解析 Docker Volume」。
Docker的概念跟傳統程式教學那種修改程式碼的做法並不相同，但越熟悉Docker，就會越感嘆這種自動化微服務設計的精妙。一起學習吧。
這篇關於在Docker版本Nextcloud加入客製化程式碼的介紹就到此為止了。文章最後要來問大家的是，要客製化Nextcloud的話，你會怎麽作呢？
- 1. 改PHP我最行，學校都教PHP。
- 2. Nextcloud不是可以改css跟logo之類的外觀嗎？
- 3. 還是老老實實地開發Nextcloud的應用程式吧。
- 4. Docker的環境變數就有很多可以調整的設定了吧？需要這麼複雜嗎？
- 5. 其它：歡迎在下面留言，分享你的看法吧！
