[TOC]

0x00 背景前述

描述:由于个人与公司团队有需求搭建一个团队共享的知识库,方便团队的技术沉淀积累与同时也方便新人入职学习了解各项工作,通过一天的找寻在网上最终入坑了BookStack方案;

weiyigeek.top-bookstack

其它方案参考

• 1.Flarum轻论坛:https://flarum.org/
• 2.各种共享笔记:Wiz (私有版本支持5用户系统要求高显得笨重)/ OneNote (公司内部使用不方便且不能存储敏感信息) / 有道云笔记 (感觉不好用)
• 3.在线文档:阿里提供的语雀(企业空间需要5999元/年-我们只是一个小Team) / 看云文档 / 开源软件ShowDoc (UI界面轻量级) / 腾讯在线文档 (个人还是偏向于自建)
• 4.Wiki软件: DokuWiki (搭建使用简单无数据库)和 MediaWiki
• 5.Wiki应用: Mindoc / Bookstack 两则都是基于 PHP 框架 laravel 开发，但个人更推荐后者使用简单UI更加大气;

Bookstack简单介绍
描述:BookStack是一个简单的、自托管的、易于使用的组织和存储信s息的平台(Simple & Free Wiki Software)。

产品特点:

• 免费和开源
• 简单API,简单的接口:WYSIWYG interface(所见即所得)
• 全文搜索和连接
• 可自定义配置
• 简单的要求，跨书分类、页面修订和图像管理功能
• 完整的角色和权限系统
• 支持多语言: BookStack include EN, FR, DE, ES, IT, JA, NL, PL, RU and more.
• 支持Markdown: Markdown Editor
• 集成身份验证: 第三方 GitHub, Google, Slack, AzureAD 与 Okta 和 LDAP ;

---

0x01 安装

官网手册:https://www.bookstackapp.com/docs/admin/installation/
环境需求:

PHP >= 7.2: Required Extensions: OpenSSL, PDO, MBstring, Tokenizer, GD, MySQL, Tidy, SimpleXML & DOM
MySQL >= 5.6: Mariadb也是可以的;
Nginx 轻量级代理web
Git 版本控制: 更新

安装方法:(三类)

• 手动安装
• 脚本安装
• docker安装

(1) 手动安装
在安装之前，请确保满足上述要求。
此项目当前使用 BookStack GitHub 存储库的分支作为提供更新的稳定通道(或许后面变得更加简单)

git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch

URL 重写规则

#Apache
Options +FollowSymLinks
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-d
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^ index.php [L]

#Nginx
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

参考:https://www.bookstackapp.com/docs/admin/installation/#manual

(2) 脚本安装
Ubuntu 20.04 Installation Script
此脚本仅适用于新操作系统，它将安装Apache、MySQL 8.0和PHP-7.4，并可能覆盖机器上的任何现有web设置。
脚本查看:https://github.com/BookStackApp/devops/blob/master/scripts/installation-ubuntu-20.04.sh

wget https://raw.githubusercontent.com/BookStackApp/devops/master/scripts/installation-ubuntu-20.04.sh
chmod a+x !$:t
./!$:t

CentOS8:
安装参考:https://github.com/blogmotion/bm-bookstack-install/blob/master/bookstack-install-centos8.sh

#!/bin/bash
# bm-bookstack-install : Installation de BookStack pour Centos 8.x
# License : Creative Commons http://creativecommons.org/licenses/by-nd/4.0/deed.fr
# Website : http://blogmotion.fr/internet/bookstack-script-installation-centos-8-18255
# BookStack : https://www.bookstackapp.com/
# Adapted from : https://deviant.engineer/2017/02/bookstack-centos7/
#set -xe
VERSION="2020.04.01"

### VARIABLES #######################################################################################################################
VARWWW="/var/www"
BOOKSTACK_DIR="${VARWWW}/BookStack"
TMPROOTPWD="/tmp/DB_ROOT.delete"
REMIRPM="http://rpms.remirepo.net/enterprise/8/remi/x86_64/remi-release-8.1-2.el8.remi.noarch.rpm"
#CURRENT_IP=$(ip addr | grep 'state UP' -A2 | tail -n1 | awk '{print $2}' | cut -f1  -d'/')
CURRENT_IP=$(hostname -i)
blanc="\033[1;37m"; gris="\033[0;37m"; magenta="\033[0;35m"; rouge="\033[1;31m"; vert="\033[1;32m"; jaune="\033[1;33m"; bleu="\033[1;34m"; rescolor="\033[0m"


### START SCRIPT #################################################################################################################### 
echo -e "${vert}"
echo -e "#########################################################"
echo -e "#                                                       #"
echo -e "#                BookStack Installation                 #"
echo -e "#                                                       #"
echo -e "#              Tested on Centos 8.1 (x64)               #"
echo -e "#                      by @xhark                        #"
echo -e "#                                                       #"
echo -e "###################### ${VERSION} #######################"
echo -e "${rescolor}\n\n"
sleep 3

echo -e "\n${jaune}SELinux disable and firewall settings ...${rescolor}" && sleep 1
sed -i s/^SELINUX=.*$/SELINUX=disabled/ /etc/selinux/config && setenforce 0
firewall-cmd --add-service=http --permanent && firewall-cmd --add-service=https --permanent && firewall-cmd --reload


### PACKAGES INSTALLATION ##########################################################################################################
echo -e "\n${jaune}Packages installation ...${rescolor}" && sleep 1
yum -y update
yum -y install epel-release # (Extra Packages for Enterprise Linux)
yum -y install git mariadb-server nginx php php-cli php-fpm php-json php-gd php-mysqlnd php-xml php-openssl php-tokenizer php-mbstring php-mysqlnd

# Add REMI repo
yum install -y $REMIRPM
if [[ $? -ne 0 ]]; then
        echo -e "\t ${rouge} ERROR on Remi RPM, please check RPM URL : $REMIRPM ${rescolor}"
        echo -e "\t ${gris} script aborted, please restart after fix it ${rescolor}"
    exit 1
fi

dnf --enablerepo=remi install -y php72-php-tidy php72-php-json

# create symlink tidy.so and enable extension in php.ini
ln -s /opt/remi/php72/root/usr/lib64/php/modules/tidy.so /usr/lib64/php/modules/tidy.so
echo "extension=tidy" >> /etc/php.ini


### Database setup ###############################################################################################################
echo -e "\n${jaune}Database installation ...${rescolor}" && sleep 1
systemctl enable --now mariadb.service
printf "\n n\n n\n n\n y\n y\n y\n" | mysql_secure_installation

mysql --execute="
CREATE DATABASE IF NOT EXISTS bookstackdb DEFAULT CHARACTER SET utf8 COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON bookstackdb.* TO 'bookstackuser'@'localhost' IDENTIFIED BY 'bookstackpass' WITH GRANT OPTION;
FLUSH PRIVILEGES;
quit"

# Set root password
DB_ROOT=$(cat /dev/urandom | tr -cd 'A-Za-z0-9' | head -c 14)
echo "MariaDB root:${DB_ROOT}" >> TMPROOTPWD && cat $TMPROOTPWD
# mysqladmin -u root password ${DB_ROOT}
mysql -e "SET PASSWORD FOR root@localhost = PASSWORD('${DB_ROOT}');FLUSH PRIVILEGES;"


### PHP-FPM setup ###############################################################################################################
echo -e "\n${jaune}PHP-FPM configuration ...${rescolor}" && sleep 1
fpmconf=/etc/php-fpm.d/www.conf
sed -i "s|^listen =.*$|listen = /var/run/php-fpm.sock|" $fpmconf
sed -i "s|^;listen.owner =.*$|listen.owner = nginx|" $fpmconf
sed -i "s|^;listen.group =.*$|listen.group = nginx|" $fpmconf
sed -i "s|^user = apache.*$|user = nginx ; PHP-FPM running user|" $fpmconf
sed -i "s|^group = apache.*$|group = nginx ; PHP-FPM running group|" $fpmconf
sed -i "s|^php_value\[session.save_path\].*$|php_value[session.save_path] = ${VARWWW}/sessions|" $fpmconf


### NGINX SETUP #################################################################################################################
echo -e "\n${jaune}nginx configuration ...${rescolor}" && sleep 1
mv /etc/nginx/nginx.conf /etc/nginx/nginx.conf.BAK

cat << '_EOF_' > /etc/nginx/nginx.conf
user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log;
pid /run/nginx.pid;
include /usr/share/nginx/modules/*.conf;
events {
    worker_connections 1024;
}
http {
    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent" "$http_x_forwarded_for"';
    access_log  /var/log/nginx/access.log  main;
    sendfile            on;
    tcp_nopush          on;
    tcp_nodelay         on;
    keepalive_timeout   65;
    types_hash_max_size 2048;
    include             /etc/nginx/mime.types;
    default_type        application/octet-stream;
    include /etc/nginx/conf.d/*.conf;
}
_EOF_

cat << '_EOF_' > /etc/nginx/conf.d/bookstack.conf
server {
  listen 80;
  
  #HTTP conf:
  #listen 443 ssl;
  #ssl_certificate /etc/pki/tls/blogmotion/monserveur.crt;
  #ssl_certificate_key /etc/pki/tls/blogmotion/monserveur.key;
  #ssl_protocols TLSv1.2;
  #ssl_prefer_server_ciphers on;
  server_name _;
  root /var/www/BookStack/public;
  access_log  /var/log/nginx/bookstack_access.log;
  error_log  /var/log/nginx/bookstack_error.log;
  client_max_body_size 1G;
  fastcgi_buffers 64 4K;
  index  index.php;
  location / {
    try_files $uri $uri/ /index.php?$query_string;
  }
  location ~ ^/(?:\.htaccess|data|config|db_structure\.xml|README) {
    deny all;
  }
  location ~ \.php(?:$|/) {
    fastcgi_split_path_info ^(.+\.php)(/.+)$;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
    fastcgi_pass unix:/var/run/php-fpm.sock;
  }
  location ~* \.(?:jpg|jpeg|gif|bmp|ico|png|css|js|swf)$ {
    expires 30d;
    access_log off;
  }
}
_EOF_

# Enable and start services
systemctl enable --now nginx.service
systemctl enable --now php-fpm.service


### BOOKSTACK INSTALLATION ################################################################################################################
echo -e "\n${jaune}BookStack installation ...${rescolor}" && sleep 1
mkdir -p ${VARWWW}/sessions # php sessions

# Clone the latest from the release branch
git clone https://github.com/BookStackApp/BookStack.git --branch release --single-branch ${BOOKSTACK_DIR}

# let composer do it's things
cd /usr/local/bin
curl -sS https://getcomposer.org/installer | php
mv composer.phar composer
cd ${BOOKSTACK_DIR}
composer install

# Config file injection
cp .env.example .env
sed -i "s|^DB_DATABASE=.*$|DB_DATABASE=bookstackdb|" .env
sed -i "s|^DB_USERNAME=.*$|DB_USERNAME=bookstackuser|" .env
sed -i "s|^DB_PASSWORD=.*$|DB_PASSWORD=bookstackpass|" .env
sed -i "s|^MAIL_PORT=.*$|MAIL_PORT=25|" .env

# Set in French if locale is FR
lang=$(locale | grep LANG | cut -d= -f2 | cut -d_ -f1)
if [[ $lang -eq "fr" ]]; then
  sed -i "s|^# Application URL.*$|APP_LANG=fr\n# Application URL|" .env
fi

# Generate and update APP_KEY in .env
php artisan key:generate --force

# Generate database tables and other settings
php artisan migrate --force

# Fix rights
chown -R nginx:nginx /var/www/{BookStack,sessions}
chmod -R 755 bootstrap/cache public/uploads storage

echo -e "\n\n"
echo -e "\t * 1 * ${vert}PLEASE NOTE the MariaDB password root:${DB_ROOT} ${rescolor}"
echo -e "\t * 2 * ${rouge}AND DELETE the file ${TMPROOTPWD} ${rescolor}"
echo -e "\t * 3 * ${bleu}Logon http://${HOSTNAME} or http://${CURRENT_IP} -> admin@admin.com:password ${rescolor}"
echo -e "\n\t${magenta} --- END OF SCRIPT (v${VERSION}) ---  \n\n\n ${rescolor}"

exit 0

(3) Docker安装
基础Docker安装BookStack:
Docker Hub:https://hub.docker.com/r/linuxserver/bookstack

环境说明:

#Docker与Docker-Compose安装参考我Docker记录的笔记
[root@weiyigeek tmp]$ docker --version
Docker version 19.03.8, build afacb8b
[root@weiyigeek tmp]$ docker-compose -v
docker-compose version 1.25.5, build 8a1c60f6

Step1.持久化目录建议以及docker专有网络

mkdir -vp /app/bookstack/{data,web}
docker network create bookstack
#573b6beffe0cf80c4718bcaec356006b5814e8a76482fe58fdc0456cd27cd56b
docker network ls
# NETWORK ID          NAME                DRIVER              SCOPE
# 573b6beffe0c        bookstack           bridge              local
# 222e290b6d38        bridge              bridge              local
# 5ff53ab796aa        host                host                local
# 665c6dab3999        none                null                local

#将bookstack网络地址加入防火墙信任即可容器间相互通信
docker network inspect bookstack
firewall-cmd --zone=trusted --add-source=172.18.0.1/16 --permanent
firewall-cmd --reload

Step2.BookStack 关键参数设置参看官网（env）

cat >.env<<'EOF'
# User Permiss
PUID=1000
PGID=1000

# Database Setting
DB_HOST=bookstack_db
DB_PORT=3306
DB_DATABASE=bookstackapp
DB_USERNAME=bookstack
DB_PASSWORD=WeiyiGeek

# Basic Setting
APP_TIMEZONE=Asia/Shanghai
APP_LANG=zh_CN
APP_ENV=production
WKHTMLTOPDF=/usr/bin/wkhtmltopdf

# Debug: Error File laravel.log
#APP_DEBUG=true
APP_URL=http://my.weiyigeek.top #optional

# LDAP General auth (有些许BUG:v.29)
#AUTH_METHOD=ldap
#LDAP_SERVER=10.10.107.245:389
#LDAP_BASE_DN=dc=weiyigeek,dc=cn
#LDAP_DN=cn=admin,dc=weiyigeek,dc=cn
#LDAP_PASS=Password2020
#LDAP_USER_FILTER=(&(uid=*))
#LDAP_VERSION=3
#LDAP_DISPLAY_NAME_ATTRIBUTE=cn
#LDAP_ID_ATTRIBUTE=uid
#LDAP_EMAIL_ATTRIBUTE=mail

# Mail Setting
#- MAIL_DRIVER=smtp
#- MAIL_FROM=service@example.com
#- MAIL_FROM_NAME="XXXX知识库"
# SMTP mail options
#- MAIL_HOST=smtpdm.aliyun.com
#- MAIL_PORT=465
#- MAIL_USERNAME=service@example.com
#- MAIL_PASSWORD=password
#- MAIL_ENCRYPTION=ssl

# Application key:Used for encryption where needed.
# Run `php artisan key:generate` to generate a valid key. 
# The only supported ciphers are AES-128-CBC and AES-256-CBC with the correct key lengths 16 . 
# APP_KEY=base64:v2qr11Dmf+wWw9j6j09udZPhSHJHw9lZ2xA7dz24YPA=
EOF

Step3.容器docker-compose.yaml

version: "3.0"
services:
  bookstack:
    image: linuxserver/bookstack
    container_name: bookstack
    env_file:
      - ./.env
    volumes:
      - /app/bookstack/web:/config
    ports:
      - 80:80
    restart: unless-stopped
    depends_on:
      - bookstack_db
    networks:
      - bookstack
     
  bookstack_db:
    image: linuxserver/mariadb
    container_name: bookstack_db
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - MYSQL_ROOT_PASSWORD=WeiyiGeek
      - MYSQL_DATABASE=bookstackapp
      - MYSQL_USER=bookstack
      - MYSQL_PASSWORD=WeiyiGeek
    volumes:
      - /app/bookstack/data:/config
    restart: unless-stopped
    ports:
      - 3366:3306
    networks:
      - bookstack

#自定义已存在的外部网络
networks:
  bookstack:
    external: true

Step4.运行指令构建容器

docker-compose up -d
#构建成功特征
bookstack       | Migrated:  2019_07_07_112515_add_template_support (0.04 seconds)
bookstack       | Migrating: 2019_08_17_140214_add_user_invites_table
bookstack       | Migrated:  2019_08_17_140214_add_user_invites_table (0.05 seconds)
bookstack       | Migrating: 2019_12_29_120917_add_api_auth
bookstack       | Migrated:  2019_12_29_120917_add_api_auth (0.07 seconds)
bookstack       | [services.d] starting services
bookstack       | [services.d] done.

$docker ps
CONTAINER ID        IMAGE                   COMMAND             CREATED             STATUS              PORTS                           NAMES
2ff08e960aa2        linuxserver/bookstack   "/init"             5 hours ago         Up 5 hours          443/tcp, 0.0.0.0:9000->80/tcp   bookstack
5b8d5dd33af0        linuxserver/mariadb     "/init"             5 hours ago         Up 5 hours          3306/tcp                        bookstack_db

#查看生效的环境变量
docker exec -it bookstack env

Step5.访问登陆系统:http://xxx.xxx.xx.x:9000,默认账号密码
用户电子邮件地址:admin@admin.com
密码:password

weiyigeek.top-

---

0x02 基础设置

1.安全设置

• 1.修改初始用户的密码和电子邮件地址
• 2.低权限用户BookStack 的数据库用户具有仅访问用于 BookStack 数据的数据库的有限权限。
• 3.禁用”目录索引”，以防止未知用户能够浏览图像。

  #Nginx
  # By default indexes are disabled on Nginx but if you have them enabled
  # add this to your BookStack server block
  location /uploads {
         autoindex off;
  }
  
  #Apache
  <Location "/uploads">
      Options -Indexes
  </Location>

• 4.Web爬网器控制:”设置自动控制。可以通过设置或在文件中覆盖此功能，如果要自定义规则，可以通过主题重写完成此操作。

  #.env
  ALLOW_ROBOTS=false

• 5.使用 Cookie 跟踪会话、记住登录次数和 XSRF 保护(需要生成申请证书)

  #.env
  SESSION_SECURE_COOKIE=true

2.多实例部署

目前，BookStack 不支持一个安装中的多个实例，但您可以通过创建多个安装并适当地配置 Web 服务器在同一服务器上设置多个实例。

按照每个实例的标准安装说明，从克隆 BookStack 到下面面创建的每个文件夹中开始

/var/www/user-docs/
/var/www/admin-docs/

Ubuntu 16.04：Apache

# /etc/apaches/sites-available/user-docs.conf
 <VirtualHost *:80>
        ServerName user-docs.example.com
        DocumentRoot /var/www/user-docs/public
        <Directory "/var/www/user-docs/public">
                AllowOverride All
                Require all granted
        </Directory>
</VirtualHost>

#命令启用每个站点
sudo a2ensite <config-file-name>
sudo a2ensite user-docs.conf #/etc/apache/sites-enabled/

#完成此操作后，重新启动 apache 以重新加载配置
sudo service apache2 restart

Ubuntu 16.04:Nginx

# /etc/nginx/sites-available/user-docs.conf
server {
  listen 80;
  listen [::]:80;

  root /var/www/user-docs/public;
  index index.php;

  server_name user-docs.example.com;

  location / {
      try_files $uri $uri/ /index.php?$query_string;
  }

  location ~ \.php$ {
      try_files $uri /index.php =404;
      fastcgi_split_path_info ^(.+\.php)(/.+)$;
      fastcgi_pass unix:/run/php/php7.2-fpm.sock;
      fastcgi_index index.php;
      fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
      include fastcgi_params;
  }
}

sudo ln -s /etc/nginx/sites-available/user-docs.conf /etc/nginx/sites-enabled/user-docs.conf
nginx -t
sudo service nginx restart

3.备份还原

BookStack 目前没有用于备份和还原的内置方法，但可以通过命令行相当简单完成(当您更新程序时候必须要备份后操作)

警告：执行以下任何操作之前，请创建数据库备份，以防止潜在的数据丢失。

备份有两种类型:静态文件与数据库记录:

# MySQL Command Syntax
mysqldump -u {mysql_user} -p {database_name} > {output_file_name}
mysqldump -u bookstack bookstackapp > bookstack.backup.sql

文件:下面是包含应备份的数据的文件和文件夹的列表

.env #包含重要的配置信息。
<bookstack_install_dir>/public/uploads/images #图像上传位置文件夹包含任何上传的图像（如果不使用 amazon s3）-在Docker不同
<bookstack_install_dir>/storage/uploads/files #附件上传位置文件夹包含上传的页面附件（仅自 BookStack v0.13 起存在） -在Docker不同

# BookStack v0.13+:将其复制到安全的地方，最好是在不同的设备上。
tar -czvf bookstack-files-backup.tar.gz .env public/uploads storage/uploads

如果要从头开始还原，请先按照安装说明进行安装，以便设置新的 BookStack 实例，但是在参照安装的时候请不要执行php artisan migrate，同时如果是安装比当前数据库备份时候高的新版本的需要在导入数据执行php artisan migrate;

# Syntax
mysql -u {mysql_user} -p {database_name} < {backup_file_name}
## Only specify the -p if the user provided has a password

# Example
mysql -u benny -p bookstack < bookstack.backup.sql

还原文件，只需将它们从备份存档复制到原始位置即可：

#如果发生错误请检查文件权限
tar -xvzf bookstack-files-backup.tar.gz

4.更新

BookStack 定期更新，仍处于测试阶段，尽管我们尝试保持平台和升级路径尽可能稳定；

#拉取更新
git pull origin release && composer install --no-dev && php artisan migrate

#清除缓存
php artisan cache:clear
php artisan view:clear

5.主题设置

描述:Bookstack另外一个强大的地方在于它可以使用自定义主题，而这些主题可以在github中找寻您喜欢的样式;

• 主题设置说明
• 更多主题

更改代码块主题：
将代码插入页面或使用 Markdown 编辑器时，您输入的文本将采用默认代码镜像配色方案突出显示;
在 BookStack 设置中，查找”自定义 HTML 头内容”设置并添加以下代码：

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/5.29.0/theme/cobalt.min.css"/>
<script>window.codeTheme='cobalt';</script>

weiyigeek.top-

6.第三方身份验证

BookStack 目前支持通过一系列第三方和社交应用程序登录。

支持第三方社交应用:

• Google
• GitHub (下面实践)
• Twitter
• Facebook
• Slack
• AzureAD (Microsoft)
• Okta
• GitLab
• Twitch
• Discord

Github第三方平台身份验证设置

#1.自动注册:从登录屏幕自动注册用户
GITHUB_AUTO_REGISTER=true

#2.如果您信任第三方登录服务，您可以启用自动电子邮件确认
GITHUB_AUTO_CONFIRM_EMAIL=false

3.GitHub Token 获取与设置

• Step1.登录时，打开GitHub 开发人员应用程序。
• Step2.单击”注册新应用程序”。输入应用程序名称（”BookStack”或自定义集名称）、”主页 URL”下指向应用实例的链接以及 BookStack 实例托管的 URL 的”授权回调 URL”，然后单击”注册应用程序”。

• Step3.将显示”客户端 ID”和”客户端机密”值。将这两个值添加到 和 变量，替换 BookStack 根文件夹中的”.env”文件中的默认假值。

  GITHUB_APP_ID=4915**************
  GITHUB_APP_SECRET=446da*************e0fc*************43a0995

  

  weiyigeek.top-

• Step4.将”APP_URL”环境变量设置为与步骤 3 中输入的域相同即http://wiki.weiyigeek.top。

• Step5.都做完了！用户现在应该能够链接他们的社交帐户在他们的帐户配置文件页，也使用他们的Github帐户注册/登录。

更多第三方平台配置参考:

• third-party-auth

7.LDAP 身份验证

描述:BookStack 可以配置为允许基于 LDAP 的用户登录。启用 LDAP 登录名时，您不能使用标准用户/密码登录登录，并且将禁用新用户注册。

当 LDAP 用户首次登录到 BookStack 时，将创建其 BookStack 配置文件，并在应用程序设置中的”注册后默认用户角色”选项下为其提供默认角色集。

#.env
# General auth
AUTH_METHOD=ldap

# The LDAP host, Adding a port is optional
LDAP_SERVER=example.com:389
# If using LDAP over SSL you should also define the protocol:
# LDAP_SERVER=ldaps://example.com:636

# The base DN from where users will be searched within
LDAP_BASE_DN=ou=People,dc=example,dc=com

# The full DN and password of the user used to search the server
# Can both be left as false to bind anonymously(否则匿名访问|注意DN需要输入完整的cn=admin + LDAP_BASE_DN)
LDAP_DN=false
LDAP_PASS=false

# A filter to use when searching for users
# The user-provided user-name used to replace any occurrences of '${user}'
LDAP_USER_FILTER=(&(uid=\${user}))

# Set the LDAP version to use when connecting to the server
LDAP_VERSION=3.0

# Set the property to use as a unique identifier for this user.
# Stored and used to match LDAP users with existing BookStack users.
# Prefixing the value with 'BIN;' will assume the LDAP service provides the attribute value as
# binary data and BookStack will convert the value to a hexidecimal representation.
# Defaults to 'uid'.
LDAP_ID_ATTRIBUTE=uid

# Set the default 'email' attribute. Defaults to 'mail'
LDAP_EMAIL_ATTRIBUTE=mail

# Set the property to use for a user's display name. Defaults to 'cn'
LDAP_DISPLAY_NAME_ATTRIBUTE=cn

# If you need to allow untrusted LDAPS certificates, add the below and uncomment (remove the #)
# Only set this option if debugging or you're absolutely sure it's required for your setup.
#LDAP_TLS_INSECURE=true

# If you need to debug the details coming from your LDAP server, add the below and uncomment (remove the #)
# Only set this option if debugging since it will block logins and potentially show private details.
#LDAP_DUMP_USER_DETAILS=true

LDAP 组同步：BookStack 能够将 LDAP 用户组与 BookStack 角色同步。

• 默认情况下，将 LDAP 组名称与忽略大小写的大小写名称的 BookStack 角色显示名称匹配。可以通过启用 LDAP 身份验证时在编辑角色时看到的”外部身份验证 ID”字段来覆盖
• 此字段可以使用帐户或组的常见名称 （CN） 填充。如果填充，将使用此字段中的 CN，并将忽略角色名称。您可以通过用逗号分隔多个 CN 来匹配它们。

  # Enable LDAP group sync, Set to 'true' to enable.
  LDAP_USER_TO_GROUPS=true
  
  # LDAP user attribute containing groups, Defaults to 'memberOf'.
  LDAP_GROUP_ATTRIBUTE="memberOf"
  
  # Remove users from roles that don't match LDAP groups.
  LDAP_REMOVE_FROM_GROUPS=false

weiyigeek.top-LDAP

注意事项:

• 1.需要在系统上安装 php-ldap 扩展,建议配置得时候将APP_DEBUG进行开启，等到没有问题得时候再关闭即可;
• 2.LDAP Group Sync 需要在LDAP中设置memberOf attribute的条目属性;

8.上传设置

在 BookStack 中有几个用于存储文件的不同选项：

• local（默认） - 文件存储在运行 BookStack 的服务器上。图像可以公开访问，由您的 Websever 提供，但附件在 BookStack 身份验证后是安全的。

  #.env
  STORAGE_TYPE=local
  
  图像上传位置： .<bookstack_install_dir>/public/uploads/images
  附件上传位置： .<bookstack_install_dir>/storage/uploads/files

• local_secure - 与本地选项相同，但 BookStack 提供图像，从而启用对映像请求的身份验证。提供更高的安全性，但系统资源密集度较高，并可能导致性能问题。

  #.env
  STORAGE_TYPE=local
  #如果要从默认存储系统切换到此选项，首先需要将现有图像上载迁移到上面列出的图像文件夹
  图像上传位置： .<bookstack_install_dir>/storage/uploads/images
  附件上传位置： .<bookstack_install_dir>/storage/uploads/files

• s3 - 在 Amazon S3 上将文件存储在外部。图片在上传时可公开访问。

单独的图像和附件存储方式:
希望通过不同的存储选项存储图像和附件，可以使用以下选项来存储图像和附件

#图像采用 Local 存储
STORAGE_IMAGE_TYPE=local 
#附件采用 Local Secure 存储
STORAGE_ATTACHMENT_TYPE=local_secure

更改上传限制

• PHP:两个主要变量 post_max_size 与 upload_max_filesize更新后需要重启 Web 服务器和 PHP；

  post_max_size = 10M
  upload_max_filesize = 10M

• Nginx:默认情况下，NGINX 的文件上载限制为 1MB 关键参数:client_max_body_size

  http {
    #...
          client_max_body_size 100m;
          client_body_timeout 120s; # Default is 60, May need to be increased for very large uploads
    #...
  }

• Apache:没有任何内置限制，您需要更改，但需要注意的是，如果您使用 apache 并启用了启用的文件mod_php，则可以在文件中设置上述 PHP 变量;

  #.htaccess
  php_value upload_max_filesize 10M
  php_value post_max_size 10M

在 BookStack 设置中，查找”自定义 HTML 头内容”设置并添加以下代码：

<script>
//#文件上传超时
//#BookStack 中的文件上载使用默认上传超时为 60 秒的 JavaScript 库
//#Set the file upload timeout to 120 seconds.
//#You can change '120' to be the number of seconds you want the timeout to be. 
window.uploadTimeout = 120 * 1000;

//#文件上传限制
//#BookStack 中的文件上传使用默认上载大小限制为 256MB 的 JavaScript 库。
//#Set the file upload limit to 1.5GB.
//#The value is defined in MB. 
window.uploadLimit = 1500;
</script>

9.导出设置

BookStack使用以下两种方式进行PDF渲染（将页面导出为PDF文档）:

• Dompdf: 使用DomPDF的好处是它不需要任何其他安装或设置，但是呈现功能受到一定程度的限制(缺省)。
• wkhtmltopdf:使用Qt WebKit呈现引擎来提供更准确的总体结果(推荐),wkhtmltopdf的预编译二进制文件可以在其网站的下载页面上找到。

  #.env
  WKHTMLTOPDF=/home/user/bins/wkhtmltopdf
  #Docker
  WKHTMLTOPDF=/usr/bin/wkhtmltopdf

UTF8mb4 / Emoji支持
描述:从BookStack v0.17开始UTF8mb4，默认的数据库字符集和排序规则允许表情符号支持

# BookStack v0.17.2或更高版本更改生成SQL
# Generate the upgrade sql and output to a 'dbupgrade.sql' file
php artisan bookstack:db-utf8mb4 > dbupgrade.sql

# Run the SQL via MySQL (Using root account)
mysql -u root < dbupgrade.sql

补充:

• 关于“密钥过长”错误:在这种情况下如果要完全支持表情符号，则最好重新创建数据库

  #1.转储数据库中的所有数据（仅数据）
  # Change 'bookstack_db' to your bookstack database name
  mysqldump -u root --no-create-info bookstack_db > bookstack_data.sql
  
  #2.重新创建数据库或创建一个新的数据库。
  
  #3.在BookStack文件夹中运行迁移数据库并重新创建所有表
  php artisan migrate
  
  #4.还原数据库并且再次运行以确保数据库是最新的。
  mysql -u root < bookstack_data.sql
  php artisan migrate

更多使用技巧参考:

• Hacking BookStack:https://www.bookstackapp.com/docs/admin/hacking-bookstack/

---

0x03 内置命令

BookStack 具有一些命令行操作，可帮助进行维护和常见操作，此处基于Laravel 框架获得，只需从 BookStack 安装文件夹中运行即可；

BookStack 特定命令的列表(-h:选项来列出命令的详细信息和选项):

# Create a new admin user
php artisan bookstack:create-admin

# Delete all activity history from the system
php artisan bookstack:clear-activity

# Delete all page revisions from the system
php artisan bookstack:clear-revisions

# Delete all page revisions from the system including update drafts
php artisan bookstack:clear-revisions -a

# Delete all page views from the system
php artisan bookstack:clear-views

# Search and remove images that are not used in page content
php artisan bookstack:cleanup-images

# Generate SQL commands that will upgrade the database to UTF8mb4
# See https://www.bookstackapp.com/docs/admin/ut8mb4-support/
php artisan bookstack:db-utf8mb4

# Rebuild the search index
# Useful if manually inserting pages into the system
php artisan bookstack:regenerate-search

# Regenerate access permissions - Used mostly in development
php artisan bookstack:regenerate-permissions

# Delete all users from the system that are not "admin" or system users
php artisan bookstack:delete-users

# Copy the permission settings of a specified, or all, shelf to their child books
php artisan bookstack:copy-shelf-permissions --all
php artisan bookstack:copy-shelf-permissions --slug=my_shelf_slug

# Update a URL in the database content of your BookStack instance.
# Searches for <oldUrl> and replaces it with <newUrl>
php artisan bookstack:update-url <oldUrl> <newUrl>
# Example:
php artisan bookstack:update-url http://docs.example.com https://demo.bookstackapp.com

# Regenerate the stored HTML content for comments from their original text content
php artisan bookstack:regenerate-comment-content

---

0x04 补充说明

1.离线迁移图片路径处理

--- (1) 查看那些图片路径为 10.10.107.202 服务器的信息进行更改
SELECT * from pages WHERE html like "%10.10.107.202%"

--- (2) 替换服务器路径为wiki.weiyigeek.top
UPDATE pages set html = REPLACE(html,"10.10.107.202","wiki.weiyigeek.top");