# bookstack教學

# 安裝



# Prerequisite(前提條件)

1. 準備好Linux OS
2. 準備好容器主機  
    [RockyLinux安裝Docker](https://kafeiou.pw/2022/02/26/3740/)  
    [RockyLinux安裝Podman](https://kafeiou.pw/2022/10/26/4326/rocky-linux-9-%E5%AE%89%E8%A3%9Dpodman/)
3. 準備好mariadb 資料庫容器  
    [RockyLinux安裝mariadb](https://kafeiou.pw/2022/10/20/4296/rockylinux-9-%E7%B0%A1%E6%98%93%E5%AE%89%E8%A3%9D-mariadb/)

# 實戰(使用docker)

### 設定容器volume

```
docker volume create bookstack_config
```

我通常能不用Dockerfile就不用，習慣直接下指令

```
docker run --restart=always -d --name=bookstack -e PUID=1000 -e PGID=1000 -e TZ=Asia/Taipei \
-v /usr/share/fonts:/usr/share/fonts -e APP_URL=https://<網址需要https>   \
-e DB_HOST=<mariadb 資料庫ip>   -e DB_PORT=3306   -e DB_USER=<帳號>   -e DB_PASS=<密碼>   -e DB_DATABASE=bookstackapp  \
-e QUEUE_CONNECTION= `#optional` -p 6875:80 -v bookstack_config:/config --restart unless-stopped   lscr.io/linuxserver/bookstack:v23.10.4-ls119

```

**<span style="color: rgb(224, 62, 45);">上面指令需要注意:</span>**  
  
1\. <span style="color: rgb(224, 62, 45);">APP\_URL </span>必須為https請準備好反向代理程式，當然也可以是ip，ip就不需要https  
  
2\. <span style="color: rgb(224, 62, 45);">DB\_HOST、DB\_PORT、DB\_USER、DB\_PASS 以及 DB\_DATABASE </span>都是mariadb database連線資訊  
  
3\. <span style="color: rgb(224, 62, 45);">6875:80</span> 將本體主機的6875拿來對應到容器的80  
  
4\. <span style="color: rgb(224, 62, 45);">/usr/share/fonts</span>使用本體的字型，這樣就不浪費空間了  
fonts目錄下，需再另外存放中文檔案，以下是免費豆腐自型

<p class="callout info">請到此下載中文字型  
[https://fonts.google.com/noto/specimen/Noto+Sans+SC](https://fonts.google.com/noto/specimen/Noto+Sans+SC)  
[https://fonts.google.com/noto/specimen/Noto+Sans+TC](https://fonts.google.com/noto/specimen/Noto+Sans+TC)</p>

  
5\. 容器 Image lscr.io/linuxserver/bookstack:<span style="color: rgb(224, 62, 45);">v23.10.4-ls119</span>

<p class="callout info">請參考 [https://github.com/BookStackApp/BookStack](https://github.com/BookStackApp/BookStack)</p>

  
6\. TZ=Asia/Taipei 系統時間

<p class="callout info">請參考[ https://worldtimeapi.org/timezone/](https://worldtimeapi.org/timezone/)</p>

<p class="callout success">安裝完畢後，請自行測試，預設帳號 <admin@admin.com> 密碼 password  
<span style="color: rgb(224, 62, 45);">登入後請修改email，修改後的email即為登入帳號；登入後請立即修改密碼</span>  
</p>

### 修改讓匯出pdf不會有亂碼  


<span style="color: rgb(224, 62, 45);">我後來發現匯出PDF功能只是將html轉為PDF檔案，並無特別排版，所以有點雞肋，但強迫症讓我必須解決中文亂碼文提</span>

```
### 進入容器
docker exec -it bookstack bash

### 刪除預設的qt5
apk del qt5-qtbase

### 修改repositories 
vi /etc/apk/repositories
### 將 3.18改成3.14
http://dl-cdn.alpinelinux.org/alpine/v3.14/main
http://dl-cdn.alpinelinux.org/alpine/v3.14/community
###

# 套用
apk update
apk upgrade
apk add wkhtmltopdf

### 測試-無法產生test.pdf 則代表失敗 
wkhtmltopdf test.html test.pdf

### 修改 .env 檔案
vi /app/www/.env
###
WKHTMLTOPDF=/usr/bin/wkhtmltopdf
ALLOW_UNTRUSTED_SERVER_FETCHING=true
###


```

<span style="color: rgb(224, 62, 45);">離開容器並且重啟，就能正常匯出中文PDF</span>

### 隱藏最近更新足跡

管理帳號登入後，請在  
<span style="color: rgb(224, 62, 45);">Settings-&gt;Customization-&gt;Custom HTML Head Content  
(設定-&gt;自訂-&gt;自訂 HTML 標題內容) </span>   
加上以下控制碼即可

```
<style>
  .tri-layout-left { visibility: hidden; }
  .tri-layout-right { visibility: hidden; }
</style>
<script>
	window.addEventListener('DOMContentLoaded', (event) => {
		const loginShowing = document.querySelector('a[href$="/login"]') == null;
		const leftPanel = document.querySelector("div.tri-layout-left");
		const rightPanel = document.querySelector("div.tri-layout-right");
		if (loginShowing) {
			leftPanel.style.visibility = 'visible';
			rightPanel.style.visibility = 'visible';
		}
	});
</script>
```

### 預設展開「章節」內容

管理帳號登入後，請在  
<span style="color: rgb(224, 62, 45);">Settings-&gt;Customization-&gt;Custom HTML Head Content  
(設定-&gt;自訂-&gt;自訂 HTML 標題內容) </span>   
加上以下控制碼即可

```
<style>
    .chapter-contents-toggle {
        display: none !important;
    }
    .inset-list {
        display: block !important;
    }
</style>
```

### 隱藏書本封面

管理帳號登入後，請在  
<span style="color: rgb(224, 62, 45);">Settings-&gt;Customization-&gt;Custom HTML Head Content  
(設定-&gt;自訂-&gt;自訂 HTML 標題內容) </span>   
加上以下控制碼即可

```
<style> 
.entity-list-item-image.bg-book { background-image: none !important; width: 5px; } .entity-list-item-image.bg-book * { display: none !important; }

.bg-book.featured-image-container-wrap .featured-image-container {
    height: 2px;
    min-height: 2px;
    background-image: none !important; 
}
.bg-book.featured-image-container-wrap *:not(.featured-image-container) {
    display: none !important;
}
</style>
```

### 讓中間文字版面變大

```
<style> 
@media screen and (min-width: 1400px) {
    .tri-layout-middle-contents {
        max-width: 1700px;
    }
}
.page-content { max-width: 1200px; }
</style> 
```

### 修改上傳檔案大小

```
docker 進入容器後，app/www/.env，設定FILE_UPLOAD_SIZE_LIMIT即可
```

# 整合網域主控站(Active Directory)

##### **<span style="color: rgb(35, 111, 161);">1. 綁定管理者角色</span>**

<p class="callout info">網域主控站新增一個群組「BookStackAdmin」</p>

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/gSuimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/gSuimage.png)

<p class="callout info">BookStack選定Admin角色，在「外部身分驗證ID」輸入BookStackAdmin，與網域群組「BookStackAdmin」綁定</p>

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/image.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/image.png)


<p class="callout success">網域使用者帳號，只要隸屬於BookStackAdmin角色，就會有BookStack系統管理者權限</p>

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/cLFimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/cLFimage.png)

##### <span style="color: rgb(35, 111, 161);">**2. 修改設定檔案，用以綁定網域帳號登，**</span>

docker容器為例子， **vi /app/www/.env**

```
AUTH_METHOD=ldap
LDAP_SERVER=<網域主控站IP>:389
LDAP_BASE_DN="DC=test,DC=com,DC=tw"
LDAP_DN="CN=book,CU=users,DC=test,DC=com,DC=tw"
LDAP_PASS="password"
LDAP_GROUP_ATTRIBUTE="memberOf"
LDAP_USER_FILTER=(&(sAMAccountName=${user}))
LDAP_VERSION=3
LDAP_ID_ATTRIBUTE=BIN;objectGUID
LDAP_EMAIL_ATTRIBUTE=mail
LDAP_DISPLAY_NAME_ATTRIBUTE=cn
LDAP_THUMBNAIL_ATTRIBUTE=thumbnailPhoto
LDAP_START_TLS=false
LDAP_USER_TO_GROUPS=true
LDAP_REMOVE_FROM_GROUPS=false
```

以上設定值需調整：

1. LDAP\_SERVER
2. LDAP\_BASE\_DN
3. LDAP\_DN
4. LDAP\_PASS

<p class="callout success">重開服務，請使用有網域管理員Domain Admins的帳號登入，測試是否能正常登入，以及是否有管理權限</p>

# 預設語系

<span class="nv">[https://www.bookstackapp.com/docs/admin/language-config/](https://www.bookstackapp.com/docs/admin/language-config/)</span>

<span class="nv">以docker 為例子，修改.env </span>

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-02/scaled-1680-/PFFimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-02/PFFimage.png)

<span class="nv">加上 APP\_LANG</span><span class="o">=zh\_TW 就可以改成繁體中文了</span>

# 刪除頁面的「修改紀錄」

##### 1. 先確認revision號碼，然後再進資料表「page\_revisions」將該紀錄刪除


[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-01/scaled-1680-/image.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-01/image.png)


##### 2. 重新編排號碼

因為刪除了<span style="color: rgb(224, 62, 45);">**\#14**</span>這個修改紀錄，咱們需要連到資料庫，找到<span style="color: rgb(224, 62, 45);">「page\_revisions」</span>這個Table，再搜尋到<span style="color: rgb(224, 62, 45);">與該書本所有相關的修改紀錄</span>，將這些紀錄的<span style="color: rgb(224, 62, 45);">「revision\_number」</span>的欄位數值修改成正確的，**<span style="color: rgb(224, 62, 45);">例如#15改成#14、#16改成#15</span>**

[![image.png](https://book.hlmt.com.tw/uploads/images/gallery/2023-12/scaled-1680-/uImimage.png)](https://book.hlmt.com.tw/uploads/images/gallery/2023-12/uImimage.png)

##### 3. 修正「修訂版本」數量


[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2023-12/scaled-1680-/D2kimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2023-12/D2kimage.png)

我們刪除紀錄，顯示出來的修改數量會錯誤，刪除了幾個，就要減少幾個。  
家人們需要連到資料庫，找到「pages」這個Table，，再搜尋到<span style="color: rgb(224, 62, 45);">該書本，<span style="color: rgb(0, 0, 0);">將欄位「revision\_count」改成正確的數量</span></span>

[![image.png](https://book.hlmt.com.tw/uploads/images/gallery/2023-12/scaled-1680-/Wyjimage.png)](https://book.hlmt.com.tw/uploads/images/gallery/2023-12/Wyjimage.png)

##### 4. 刪除「<span style="color: rgb(224, 62, 45);">**稽核紀錄**</span>」

兄弟我們需要連到資料庫，找到「activities」這個Table，<span style="color: rgb(224, 62, 45);"><span style="color: rgb(0, 0, 0);">將欄位「Type」裡面有字樣為"revision delete"的資料行刪除</span></span>

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2023-12/scaled-1680-/dJfimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2023-12/dJfimage.png)

##### **<span style="color: rgb(224, 62, 45);">為何想要「刪除修改紀錄」</span>**

這個系統很適合拿來做成ISO線上查閱系統，也適合所有ISO文件雲端化，進而以web方式呈現；  
Web化的ISO文件需要幾件事情讓讓稽核員信服：

1. 資通安全控管(防火牆，限定IP)
2. 風險管控、軟體確效
3. 主管確認流程、上架流程
4. 修訂版本、差異

第4項最麻煩，一般公司常常有些資料弄錯，我們需要神不知鬼不覺將資料修正，並且不讓稽核員發現記缺失，才會有刪除「修改紀錄」的需求。

# 封面

##### 書本封面

<p class="callout info">書本的封面為 440x250 ， 這個系統吃素不化妝的，建議設定封面會好看多了</p>

[![2023-12-14 09_41_09-About the World Book and Copyright Day in Brazil _ UNESCO.png](https://book.kafeiou.pw/uploads/images/gallery/2023-12/scaled-1680-/2023-12-14-09-41-09-about-the-world-book-and-copyright-day-in-brazil-unesco.png)](https://book.kafeiou.pw/uploads/images/gallery/2023-12/2023-12-14-09-41-09-about-the-world-book-and-copyright-day-in-brazil-unesco.png)

# bookstack好用功能「變動日誌」，可用來當作ISO文管系統了

<p class="callout info">每次ISO稽核，稽核員一定會查核「文件的修訂紀錄」、「文件是否有回收機制」、「文件不可下載、列印」等功能</p>

#### <span style="color: rgb(53, 152, 219);">**令人驚艷的是bookstack居然有修訂紀錄的功能，而且使用上非常方便，只要在點選「儲存頁面」前，將編修原因寫在「設定變更日誌」就可以了。**</span>

##### <span style="color: rgb(224, 62, 45);">**修改完畢，先點選下方圖示「設定變更日誌」，輸入「變更理由」。**</span>

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-01/scaled-1680-/En6image.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-01/En6image.png)

##### 下圖①為變更理由，輸入完畢按一下儲存頁面即可。

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-01/scaled-1680-/aVeimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-01/aVeimage.png)

##### 查看版本變動日誌

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-01/scaled-1680-/Zppimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-01/Zppimage.png)

原本我以為沒有<span style="color: rgb(224, 62, 45);">**commit message**</span>這功能，還想說要自己來改程式。我以前寫過php 2、php 3，現在都8了，真的很不自量力。

[![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-01/scaled-1680-/e6mimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-01/e6mimage.png)

# bookstack如何崁入影片(撥放狀態)

<p class="callout info">若沒有串流網站或是影片不放在YT，就只能上傳影片檔案，然後引用做成網頁撥放狀態</p>

1. 上傳影片檔案  
    [![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/xVEimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/xVEimage.png)
    
    [![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/NU1image.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/NU1image.png)  
    **檔案上傳後，請複製檔案網址**
    
      
    [![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/7rximage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/7rximage.png)
2. 插入/編輯影片  
      
    回到書本編輯狀態-&gt;找到「插入/編輯影片」功能
    
    [![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/NPKimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/NPKimage.png)
    
    **貼上步驟1複製的網路連結**  
      
    [![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/xrmimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/xrmimage.png)  
    切換到「Embed」-&gt;保存
    
    [![image.png](https://book.kafeiou.pw/uploads/images/gallery/2024-03/scaled-1680-/Emhimage.png)](https://book.kafeiou.pw/uploads/images/gallery/2024-03/Emhimage.png)
3. 完成

<video controls="controls" height="150" width="300"><source src="https://book.kafeiou.pw/attachments/2"></source></video>