![bookstack0.jpeg](/static/img/d905d95feb04eb4295f61f381dde7e24.bookstack0.webp)

> BookStack是一个基于PHP和MariaDB的知识管理系统。它以“书架”模式组织知识，结构清晰，支持WYSIWYG和Markdown编辑，并具备全文搜索、权限管理等功能。文章详细指导了如何使用Docker Compose部署BookStack，包括数据库配置和Nginx反向代理。部署过程简单，资源消耗低，应用和MariaDB总内存占用约100MB，适合个人或企业内部知识管理。



# 1. 介绍

Bookstack如其名所示，书架。就像我们去图书馆，有社科类的书柜，有科技类的书柜，每个书柜摆满各种各样的书。Bookstack以“像书架一样组织知识”为核心理念，将内容结构设计为Shelves → Books → Chapters → Pages 的层次体系，因此能够依据逻辑顺序逐层构建知识结构，降低文档散乱的问题。它简洁易用，界面风格统一，学习曲线相对平缓，即使是非技术人员可以很容易就上手。

# 2. 技术栈和特点

BookStack 基于 PHP（Laravel 框架）构建，数据库使用MySQL/MariaDB，即标准的LAMP/LNMP架构。部署起来和Wordpress感觉很像。它具有支持角色与权限管理，多语言界面，全文搜索等特点。文档编辑器支持WYSIWYG和Markdown两种形式。除了常规的用户名密码验证外，还支持设置MFA。对于企业环境的部署，还支持OIDC，SAML2.0，LDAP等方式集成统一认证，从而更好地与现有基础设施融合。

不过，Bookstack的生态插件比较少，但对于个人或企业内部使用是足够了。而我是把它作为琐碎知识的集中管理的地方，内容涵括服务器，网络，编程，语言学习以及其他的技能。而最早我是使用Wordpress管理这一切的，但是现在我的博客只用于系统地记录技术上的内容。

# 3. 部署

最简单的方法还是使用容器进行部署，由于我的服务器上已经有一个单独的Nginx给所有的应用做反向代理，所以我直接将Bookstack部署在Nginx后面就好了。

## 3.1 准备工作

我使用了linuxserver的镜像，下载bookstack和mariadb。通过bookstack自带的功能来生成App Key。

```bash
docker pull lscr.io/linuxserver/bookstack:`latest`
docker pull lscr.io/linuxserver/mariadb:latest

docker run -it --rm --entrypoint /bin/bash lscr.io/linuxserver/bookstack:latest appkey
base64:xpAY8sV6hmZ/loCvfPZ1wRPLkd2f5lODPAL7aKtawPw=
```

新建了bookstack的Docker网络，nginx的Docker网络是原来就有的。

## 3.2 Docker Compose文件

- 使用2个服务，分别为bookstack和mariadb
- 设置时区使用APP_TIMEZONE
- 数据卷都是映射到内部的/config文件夹
- 只用expose来记录一下应用使用的端口
- 敏感数据使用了环境变量

```yaml
services:
  bookstack:
    image: lscr.io/linuxserver/bookstack:latest
    container_name: bookstack
    environment:
      - PUID=1000
      - PGID=1000
      - APP_TIMEZONE=Asia/Shanghai
      - APP_URL=https://bookstack.example.com
      - APP_KEY=${APP_KEY}
      - DB_HOST=bookstack_db
      - DB_PORT=3306
      - DB_DATABASE=bookstack
      - DB_USERNAME=bookstack
      - DB_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./bookstack_app_data:/config
    networks:
      - nginx
      - bookstack
    expose:
      - 80
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:latest
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - MYSQL_ROOT_PASSWORD=${DB_ROOT_PASSWORD}
      - MYSQL_DATABASE=bookstack
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./bookstack_db_data:/config
    networks:
      - bookstack
    expose:
      - 3306
    restart: unless-stopped

networks:
  nginx:
    external: true
  bookstack:
    external: true
```

## 3.3 环境变量

可以在Docker Compose文件所在的目录下新建一个`env`文件。如果是使用Portainer来部署stack，则可以直接设置环境变量。文件内容如下：

```plain
APP_KEY=base64:xpAY8sV6hmZ/loCvfPZ1wRPLkd2f5lODPAL7aKtawPw=
DB_PASSWORD=BOOKSTACK_DB_PASSWORD
DB_ROOT_PASSWORD=MYSQL_ROOT_PASSWORD
```

# 3.4 Nginx配置文件

其实就可以将服务都跑起来了，只不过是没有反向代理，无法访问服务而已。这时再配置Nginx的配置文件，确认没问题了，再重启Nginx的服务，然后就可以访问bookstack了。

```bash
server {
    listen 443 ssl;
    server_name bookstack.example.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    # SSL/TLS Security Settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # Enable HSTS
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    location / {
        proxy_pass http://bookstack:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

	client_max_body_size 50M; 
    }
}
```

# 4. 使用教程

## 4.1 设置管理员账号

其实在Docker Compose文件里并没有指定bookstack的admin用户和密码。它默认账号是`admin@admin.com`，默认密码是`password`。

![bookstack1.jpeg](/static/img/c21f06dd9e317a02d30f5b7c70f7f417.bookstack1.webp)

登录进来之后，赶紧改密码。点击自己的账号，选择My Account。

![bookstack2.jpeg](/static/img/75670673afecded26908d804cfa27389.bookstack2.webp)

左侧选择Profile Details，可以更改自己的显示名，邮箱地址和头像。

![bookstack3.jpeg](/static/img/a170ac8ad14758f8be4a8fd8e317f040.bookstack3.webp)

选择Access & Security可以更改密码，并设置MFA。我是使用了谷歌的Authenticator设置了MFA。

![bookstack4.jpeg](/static/img/11c75bf73a7468756e505c732baab4c4.bookstack4.webp)


## 4.2 应用设置

在应用设置里，可以设置是否是公开的站点，默认是否，还有应用的名称以及图标等。此外还可以进行用户和角色方面的设置。

![bookstack5.jpeg](/static/img/d3bd247b510dea1f8df9f83c27754ce4.bookstack5.webp)


## 4.3 文档相关

可以创建书架和书，在每本书里可以再创建章节和页面。应用还有一个全文搜索的搜索栏。

![bookstack6.jpeg](/static/img/7f1e7374c8e753955a2567fd7f116509.bookstack6.webp)

# 5. 资源利用率

新建的bookstack，整体消耗了大概100M的内存，其中应用消耗了70M左右的内存，Mariadb消耗了30M左右的内存。两者的CPU使用率都非常低。

Docker部署Bookstack

![portainer0.jpeg](/static/img/349f557bc840a699617f64e438ee6681.portainer0.webp)

>在将Portainer升级到Community Edition 2.33.5 LTS版本后，遇到了本地环境无法加载、Stack管理失效的问题。尽管容器本身仍在运行，但Portainer界面显示环境为“Down”，且无法通过UI管理现有Stack。尝试了多种方法，包括重建Portainer容器、删除Portainer数据库并重新初始化，但这导致Stack虽然可见，却带有“有限控制”的提示，且无法正常部署。 尝试重新部署Stack时，系统提示同名Stack已存在。最终的解决方案是：发现重新部署的Stack使用了新的项目ID，导致无法关联旧数据。通过删除新Stack的数据，并将旧Stack的数据文件夹复制到新项目ID对应的位置，然后执行docker compose up，成功恢复了所有Stack及其数据，解决了管理难题。



# 1. Portainer容器升级后加载环境失败

事情发生的原因是打开Portainer的管理界面，有提示让我升级到LTS版本。我手欠，就升级到了Community Edition
2.33.5 LTS版本。当我再打开Portainer时，登录界面可以正常登录。本地环境也是显示Up的，但是只要一点本地环境，那个状态就变成Down了。

![portainer1.jpeg](/static/img/47f00c47cc4ce651b521aef9676fccc8.portainer1.webp)

我在服务器上查看容器的状态，倒是没受影响。但是无法进行任何的更改了，因为原来是通过Portainer的UI界面来管理Stack的。而在服务器上，存放Docker-Compose文件的地方和实际存放容器数据的地方并不在一起。

# 2. 重建容器

我尝试重新拉镜像并重新创建容器，可以进入到本地环境的管理界面。虽然显示有stacks，但是只能看见portainer自己的stack，别的stack都没有了。

![portainer4.jpeg](/static/img/fc4c4e0887a20bebc44aa19ae1d5eaaa.portainer4.webp)

但是点开容器选项，发现容器都还在。容器的管理也都是好用的。

![portainer5.jpeg](/static/img/6f50437ef8019763daef672176d32e58.portainer5.webp)

# 3. 重建Stack

我想，既然不显示，那我就再重建一下Stack就好了。首先需要切换到root用户，再进入到`/data/compose`文件夹下。通过在Portainer的Container界面里查看Docker Compose文件的位置找到它。

![portainer6.jpeg](/static/img/bbc8d1c1e8aff252dc537b9f832fbc1d.portainer6.webp)

然后复制内容到Portainer GUI的`Stacks > Add Stack`菜单下，再Deploy。

![portainer7.jpeg](/static/img/1c106eeb0895fc278eebbbef8167a53b.portainer7.webp)

这时又出现了无法部署的情况，说是同名的Stack已经存在了。

# 4. 重建Portainer

后来我实在没有办法了，只能将Portainer自己的本地数据库给删除了。根据你Portainer的Docker Compose文件的不同，实际位置不一定相同。在容器内部是在`/data`文件夹下面。因为Portainer并没有提供Shell，无论是bash还是sh都没有。所以依赖于你映射出来的文件。

我自己的Portainer的Docker Compose文件是这样的。我没有放到Nginx的反向代理后面，因为我不想因为Nginx的原因导致我无法管理到其他的容器。确切地说，我的Nginx也是被Portainer管理的。

```yaml
services:
  portainer:
    image: portainer/portainer-ce:latest
    container_name: portainer
    restart: always
    ports:
      - "9443:9443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - ./portainer_data:/data
      - /etc/letsencrypt/live/zenseek.site/fullchain.pem:/certs/fullchain.pem
      - /etc/letsencrypt/live/zenseek.site/privkey.pem:/certs/privkey.pem
    command: >
      --sslcert /certs/fullchain.pem
      --sslkey /certs/privkey.pem
```

将Portainer的容器停掉，再将`/data/portainer.db`删除。删除前先备份一份到别的地方。再重新启动容器，因为它自身的数据库没有了，它会当成是新的实例，重建本地的数据库。

![portainer2.jpeg](/static/img/034fce0f0ee7b34b6239feef78138125.portainer2.webp)

这时就和新创建的Portainer实例一样需要设置管理员账号密码。但是进去之后是可以直接看到本地环境的，也可以点进去。

![portainer3.jpeg](/static/img/bae031e9d86e63b542daae6f578db386.portainer3.webp)

当我满心欢喜地进到Stack选项的时候，发现Stack都回来了。但是后面标识了是有限的控制。这种情况只有是在不使用Porainer直接在本地Docker Compose Up起来的stack才会这样。因为它的Docker Compose文件和data是放在不同的地方，且需要root权限。即使我在存放Docker Compose文件的文件夹下Docker Compose Down也是不好用的。在这种情况，我既不能通过Docker CLI也不能通过Portainer来管理Stack。

# 5. 解决方案

中间我问了Gemini，ChatGPT，Clause和Deepseek，也尝试了很多的方法。发现StackOverflow上也有很多人反应同样的问题，但是上面的解决方案对于我并不好用。

这时我想到刚才的报错说是有容器占用了那个stack，我就想能不能把那个容器删除了再部署呢？但是我就怕，删除容器后，数据恢复就没有了。本来使用Portainer是为了方便的，结果出了这种情况，导致无法管理Stack。早知道这样，还不如一个文件夹一个文件夹部署Docker Compose的文件和数据了。

但是在走投无路的情况下，我找了不是那么重要的容器删除了。然后进行重新再Add Stack，我发现可以部署了，而且小叹号也没有了。但是数据呢？全没了，这一个新的部署。

![portainer9.jpeg](/static/img/dabea587866dcaeaae40905c1098067a.portainer9.webp)

在细心的观察下，我发现新的部署使用了不同的项目ID，因此导致无法加载过去的数据。我把Docker Compose Down掉后，将新的项目下的数据都删除，将就项目ID的数据文件夹复制过来。再Docker Compose Up一下，一切就完好如初了。问题就这样解决了。

![portainer10.jpeg](/static/img/99743dac142ededb4e51c6385c760da0.portainer10.webp)

Portainer - 加载环境失败

![wsl0.jpeg](/static/img/854336c96f4580d984f06910b2cda1b7.wsl0.webp)

> 本文详细介绍了当公司电脑连接VPN后，WSL中的Ubuntu实例无法访问外部网络的常见问题及其解决方案。通过修改WSL Ubuntu内部的/etc/wsl.conf文件，成功解决了网络连接和域名解析的难题，确保WSL Ubuntu在VPN环境下也能顺畅地访问外部资源。



当公司电脑连接到VPN后，WSL的Ubuntu就无法访问外部网络。

# 1. 查看WSL版本

```cmd
> wsl --version

WSL version: 2.6.1.0
Kernel version: 6.6.87.2-1
WSLg version: 1.0.66
MSRDC version: 1.2.6353
Direct3D version: 1.611.1-81528511
DXCore version: 10.0.26100.1-240331-1435.ge-release
Windows version: 10.0.26200.6584
```

# 2. 升级WSL

先关闭WSL再升级。

```cmd
> wsl --shutdown
> wsl --upgrade
```

# 3. 创建WSL配置文件

在Windows系统下，创建`C:\Users\USER_NAME\.wslconfig`。内容如下：


```cmd
[wsl2]
networkingMode=mirrored
dnsTunneling=true
```

再重新打开WSL的终端，看可否ping通外部网络。我可以ping通8.8.8.8，但是在`sudo apt update`的时候无法连接到镜像服务器。报错显示的无法解析镜像服务器的域名。

# 4. 查看Windows防火墙

以Admin身份打开Powershell。

```powershell
PS C:\WINDOWS\system32> Get-NetFirewallHyperVVMSetting -PolicyStore ActiveStore -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}'


Name                  : {40E0AC32-46A5-438A-A0B2-2B479E8F2E90}
Enabled               : True
DefaultInboundAction  : Block
DefaultOutboundAction : Allow
LoopbackEnabled       : True
AllowHostPolicyMerge  : True
```

如果`DefaultOutboundAction`的行为是Block的话就需要设置为Allow。我的是没有问题的。

`Set-NetFirewallHyperVVMSetting -Name '{40E0AC32-46A5-438A-A0B2-2B479E8F2E90}' -DefaultOutboundAction Allow`

# 5. 查看WSL内的WSL配置

将最后一项的`generateResolvConf`改成true。

```bash
> cat /etc/wsl.conf

[automount]
enabled = true
root = /mnt/
options = "metadata,umask=22,fmask=11"

[interop]
enabled = true
appendWindowsPath = true

[network]
generateResolvConf = false
```

关闭WSL并重新打开WSL的终端，网络就通了。

WSL - 解决VPN连接下无法访问网络的问题

# 1. 创建项目

## 1.1 VSCode创建项目

使用VS Code来创建项目。 `Ctrl + Shift + P`打开命令栏，选择`Python Create Environment`，使用`Venv`并确定要使用的Python的版本。

![image.png](/static/img/c37caae0da67d1a6d4bf4f3a07112574.image.webp)

启用Python虚拟环境，查看现在的Python版本，并安装FastAPI。

```cmd
> .\.venv\Scripts\Activate.ps1
> Get-Command python

> python -m pip install --upgrade pip
> pip install "fastapi[standard]"
```

## 1.2 VSCode设置Git

我的Git已经设置全局账号和邮箱里。

```cmd
> git init

# 设置Git账号和邮箱以及仓库地址。
> git config --global user.name "Your Name"
> git config --global user.email "your.email@example.com"
> git remote add origin https://example.repo

# 检查Git的配置
> git config --global --list 
```

# 2. 登录模块

将登录以及下发Token等的功能放到`router/auth.py`，`main.py`再调用它。

安装JWT，`pip install PyJWT[crypto]`。