201 lines
8.5 KiB
Markdown
201 lines
8.5 KiB
Markdown
|
---
|
|||
|
title: 开始使用
|
|||
|
configurations:
|
|||
|
prism.plugins: 'command-line; treeview'
|
|||
|
---
|
|||
|
---
|
|||
|
|
|||
|
跟随下面的指导,你将可以手动安装运行 ph-Bookshelf。
|
|||
|
|
|||
|
## 安装配置 Web 服务器以及 PHP 运行时
|
|||
|
|
|||
|
首先,在你的服务器上安装并配置好一台 Web 服务器。尽管任意的支持 URL 重写的 Web 服务器都可以使用,我们推荐 Apache2,它是 ph-Bookshelf 维护者进行和部署的首选环境。
|
|||
|
|
|||
|
安装完成后,参考 [Web Server 配置](./web-server)来进行一些额外设置。
|
|||
|
|
|||
|
然后,安装 PHP 运行环境并配置 Web 服务器以支持 PHP。
|
|||
|
|
|||
|
> ph-Bookshelf 使用的是几乎最新版本的 php 8.2。然而很多的主流服务器的默认仓库会安装的 php 版本都要更旧。所以安装的时候,注意 PHP 版本不要低于 8.2。
|
|||
|
>
|
|||
|
> <pre
|
|||
|
> class="command-line"
|
|||
|
> data-output="2-5"
|
|||
|
> ><code class="lang-bash"
|
|||
|
> >php -v
|
|||
|
> PHP 8.2.4 (cli) (built: Mar 16 2023 14:37:38) (NTS)
|
|||
|
> Copyright (c) The PHP Group
|
|||
|
> Zend Engine v4.2.4, Copyright (c) Zend Technologies
|
|||
|
> with Zend OPcache v8.2.4, Copyright (c), by Zend Technologies</code></pre>
|
|||
|
|
|||
|
## 配置网站代码
|
|||
|
|
|||
|
将 ph-Bookshelf 的[源代码][source]克隆到你的 Web 根目录,然后,使用 [composer] 来为 ph-Bookshelf 安装依赖:
|
|||
|
|
|||
|
[source]: https://github.com/suk-ws/ph-Bookshelf
|
|||
|
[composer]: https://getcomposer.org/download/
|
|||
|
|
|||
|
<pre
|
|||
|
class="command-line"
|
|||
|
data-user="root"
|
|||
|
data-output="2-8, 14-19, 21-52"
|
|||
|
><code class="lang-bash"
|
|||
|
>git clone https://github.com/suk-ws/ph-bookshelf.git ph-bookshelf
|
|||
|
Cloning into 'ph-bookshelf'...
|
|||
|
remote: Enumerating objects: 860, done.
|
|||
|
remote: Counting objects: 100% (390/390), done.
|
|||
|
remote: Compressing objects: 100% (234/234), done.
|
|||
|
remote: Total 860 (delta 212), reused 314 (delta 144), pack-reused 470
|
|||
|
Receiving objects: 100% (860/860), 822.58 KiB | 2.09 MiB/s, done.
|
|||
|
Resolving deltas: 100% (461/461), done.
|
|||
|
cd ph-bookshelf
|
|||
|
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
|
|||
|
php -r "if (hash_file('sha384', 'composer-setup.php') === '55ce33d7678c5a611085589f1f3ddf8b3c52d662cd01d4ba75c0ee0459970c2200a51f492d557530c71c15d8dba01eae') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
|
|||
|
php composer-setup.php
|
|||
|
php -r "unlink('composer-setup.php');"
|
|||
|
Installer verified
|
|||
|
All settings correct for using Composer
|
|||
|
Downloading...
|
|||
|
|
|||
|
Composer (version 2.5.5) successfully installed to: /home/sukazyo/composer.phar
|
|||
|
Use it: php composer.phar
|
|||
|
php composer.phar install
|
|||
|
Installing dependencies from lock file (including require-dev)
|
|||
|
Verifying lock file contents can be installed on current platform.
|
|||
|
Package operations: 13 installs, 0 updates, 0 removals
|
|||
|
- Downloading symfony/polyfill-mbstring (v1.27.0)
|
|||
|
- Downloading gregwar/rst (v1.0.6)
|
|||
|
- Downloading symfony/polyfill-php80 (v1.27.0)
|
|||
|
- Downloading symfony/deprecation-contracts (v3.2.0)
|
|||
|
- Downloading psr/event-dispatcher (1.0.0)
|
|||
|
- Downloading nette/utils (v4.0.0-RC3)
|
|||
|
- Downloading nette/schema (v1.2.3)
|
|||
|
- Downloading dflydev/dot-access-data (v3.0.2)
|
|||
|
- Downloading league/config (v1.2.0)
|
|||
|
- Downloading league/commonmark (2.3.8)
|
|||
|
- Downloading symfony/polyfill-ctype (v1.27.0)
|
|||
|
- Downloading symfony/yaml (v6.2.5)
|
|||
|
- Downloading xemlock/php-latex (dev-master d60bf4c)
|
|||
|
- Installing symfony/polyfill-mbstring (v1.27.0): Extracting archive
|
|||
|
- Installing gregwar/rst (v1.0.6): Extracting archive
|
|||
|
- Installing symfony/polyfill-php80 (v1.27.0): Extracting archive
|
|||
|
- Installing symfony/deprecation-contracts (v3.2.0): Extracting archive
|
|||
|
- Installing psr/event-dispatcher (1.0.0): Extracting archive
|
|||
|
- Installing nette/utils (v4.0.0-RC3): Extracting archive
|
|||
|
- Installing nette/schema (v1.2.3): Extracting archive
|
|||
|
- Installing dflydev/dot-access-data (v3.0.2): Extracting archive
|
|||
|
- Installing league/config (v1.2.0): Extracting archive
|
|||
|
- Installing league/commonmark (2.3.8): Extracting archive
|
|||
|
- Installing symfony/polyfill-ctype (v1.27.0): Extracting archive
|
|||
|
- Installing symfony/yaml (v6.2.5): Extracting archive
|
|||
|
- Installing xemlock/php-latex (dev-master d60bf4c): Extracting archive
|
|||
|
Generating autoload files
|
|||
|
7 packages you are using are looking for funding.
|
|||
|
Use the `composer fund` command to find out more!
|
|||
|
</code></pre>
|
|||
|
|
|||
|
如果你遇到了以下的报错:
|
|||
|
|
|||
|
```text
|
|||
|
Problem 1
|
|||
|
- Root composer.json requires PHP extension ext-dom * but it is missing from your system. Install or enable PHP's dom extension.
|
|||
|
Problem 2
|
|||
|
- xemlock/php-latex is locked to version dev-master and an update of this package was not requested.
|
|||
|
- xemlock/php-latex dev-master requires ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.
|
|||
|
Problem 3
|
|||
|
- xemlock/php-latex dev-master requires ext-dom * -> it is missing from your system. Install or enable PHP's dom extension.
|
|||
|
- xemlock/php-latex is locked to version dev-master and an update of this package was not requested.
|
|||
|
|
|||
|
To enable extensions, verify that they are enabled in your .ini files:
|
|||
|
- /etc/php/8.2/cli/php.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/10-opcache.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/10-pdo.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-calendar.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-ctype.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-curl.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-exif.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-ffi.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-fileinfo.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-ftp.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-gettext.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-iconv.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-mbstring.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-phar.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-posix.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-readline.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-shmop.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-sockets.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-sysvmsg.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-sysvsem.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-sysvshm.ini
|
|||
|
- /etc/php/8.2/cli/conf.d/20-tokenizer.ini
|
|||
|
You can also run `php --ini` in a terminal to see which files are used by PHP in CLI mode.
|
|||
|
Alternatively, you can run Composer with `--ignore-platform-req=ext-xml --ignore-platform-req=ext-dom` to temporarily ignore these required extensions.
|
|||
|
```
|
|||
|
|
|||
|
尝试安装 php 插件 `xml` 来解决问题。
|
|||
|
|
|||
|
> 对于不同的 php 安装方式,安装插件的方式也会有不同。如果你和我一样都是在 Debian 上通过仓库安装的最新版 php,可以通过 apt 来安装 php 插件:`# apt install php-xml`{.lang-shell-session}。如果你是用的是其它的安装方式,尝试搜索 *php enable extension xml* 来解决这类问题。
|
|||
|
|
|||
|
## 配置网站安全设置
|
|||
|
|
|||
|
*我们正在努力在代码层面实现保护以避免任何形式的攻击*
|
|||
|
|
|||
|
ph-bookshelf 默认并不会对能够打开的文件路径做出限制。这意味着在生产服务器上,你最好通过 PHP 的 [`open_basedir`](https://www.php.net/manual/en/ini.core.php#ini.open-basedir) 设置网站所能够访问的路径,以避免路径构建攻击。
|
|||
|
|
|||
|
最简单的方式,就是通过在网站根目录放置 `.user.ini` 文件并在此处设置 `open_basedir` 属性:
|
|||
|
|
|||
|
```ini
|
|||
|
open_basedir = /path/to/your/ph-bookshelf
|
|||
|
```
|
|||
|
|
|||
|
当然,这个属性也可以在 Apache 服务配置器中设置,像以下这样:
|
|||
|
```apacheconf
|
|||
|
<VirtualHost _default_:443>
|
|||
|
|
|||
|
ServerName book.example.com
|
|||
|
DocumentRoot /path/to/your/ph-bookshelf
|
|||
|
|
|||
|
# ...any others
|
|||
|
|
|||
|
php_admin_value open_basedir /path/to/your/ph-bookshelf
|
|||
|
|
|||
|
# ...any others
|
|||
|
|
|||
|
</VirtualHost>
|
|||
|
```
|
|||
|
|
|||
|
### 如果你使用了软链接
|
|||
|
|
|||
|
`open_basedir` 会解析文件的绝对链接然后进行访问控制,这意味着,如果你的网站,或者是你的 `/data` 目录是通过软连接挂载进来的,你需要在 `open_basedir` 里面添加上软链接的目标目录。
|
|||
|
|
|||
|
For example, 如果你的目录结构像是以下这样:
|
|||
|
```treeview
|
|||
|
/
|
|||
|
|-- path/
|
|||
|
| └── to/
|
|||
|
| └── your/
|
|||
|
| └── ph-bookshelf
|
|||
|
| |-- .user.ini
|
|||
|
| |-- .htaccess
|
|||
|
| |-- index.php
|
|||
|
| |-- data/ -> /data-drive/books
|
|||
|
| └── ...
|
|||
|
└── data-drive/
|
|||
|
└── books/
|
|||
|
└── bookshelf.xml
|
|||
|
└── ...
|
|||
|
```
|
|||
|
|
|||
|
那么你将需要这样设置 `open_basedir`
|
|||
|
```ini
|
|||
|
open_basedir = /path/to/your/ph-bookshelf:data-drive/books
|
|||
|
```
|
|||
|
|
|||
|
## 完成搭建
|
|||
|
|
|||
|
配置完成上面这些之后,你就可以将 `/path/to/your/ph-bookshelf` 作为你的 Web 服务器根目录来建立一个站点,至此,你已经完成了 ph-Bookshelf 站点的搭建。
|
|||
|
|
|||
|
现在,在 `/path/to/your/ph-bookshelf/data` 目录下,你可以去配置你的 bookshelf.xml 和各种书籍了。
|
|||
|
|
|||
|
*data 模板正在 WIP 当中* <!-- todo -->
|