安装Zdoc应用

摘要：本文介绍在 Linux 环境下将喧喧文档（zdoc）部署到喧喧服务端的方法，涵盖环境检查、程序安装、配置与授权复用、服务重启及访问验证，适用于 xxd 11.1 及以上版本。

本篇目录

适用范围：Linux 环境，xxd 11.1 及以上版本、xxb 11.x，以及 zdoc 22.6（PHP 8.4 加密包）。其他版本请先确认兼容性。

本手册介绍如何在现有喧喧服务端中部署喧喧文档（zdoc），包括安装程序、导入配置与授权、重启服务和验证功能。

一、部署说明

喧喧文档（zdoc）由 xxd（喧喧服务端）托管，使用 xxd 提供的运行环境和入口。部署时需要注意以下关系：

程序目录：<xxd 根目录>/zdoc ，与 site/ （xxb）同级。
运行环境：使用 xxd 内置的 PHP 8.4 和 ionCube Loader，无需另行安装 PHP 或 Web 服务器。
数据库：与 xxb 共用同一个 MySQL 数据库，以及同一套用户和组织数据。
登录方式：默认通过 xxd 派发的 authToken 完成单点登录，不提供独立的账号密码登录页。

部署流程：确认环境 → 安装程序并设置权限 → 导入 xxb 的配置与授权 → 重启 xxd → 访问并验证。

部署完成后的目录结构如下：

<xxd 根目录>/
├── site/                          # xxb，已存在
│   └── config/
│       ├── my.php                 # 数据库等配置
│       └── license/xxb.php        # 站点授权文件
├── zdoc/                          # 本手册安装的程序目录
│   ├── config/
│   │   ├── my.php                 # 从 site/config/my.php 复制
│   │   └── license/zentao.txt     # 从 site/config/license/xxb.php 复制
│   └── www/index.php
├── php/                           # xxd 内置 PHP 8.4
├── xxd
└── start.sh

二、部署前准备

项目	要求	说明
xxd	11.1 及以上版本	11.0 及以下版本不提供 `/zdoc` 路由。部署后可通过启动日志中的 ZDoc 相关提示检查挂载情况。
xxb	11.x	已部署并能正常使用，配置及授权文件位于 `site/config/` 下。
zdoc	22.6（PHP 8.4 加密包）	安装包应与 xxd 内置 PHP 8.4 运行环境匹配。
数据库	MySQL 5.7 / 8.0，utf8mb4	与 xxb 共用数据库，无需单独新建数据库或数据库用户。

三、安装程序并设置权限

3.1 确认 xxd 根目录

xxd 根目录内包含 xxd 、start.sh 和 site/ 。常见位置如下：

部署方式	xxd 根目录
独立包	xxd 的实际解压目录，例如 `/opt/xxd` 。
一键包	`/opt/zbox/run/xxd` 。

以下安装命令以一键包目录为例；使用独立包或其他路径时，请替换为实际目录。进入目录后，确认 xxb 配置文件存在：

cd /opt/zbox/run/xxd
ls site/config/my.php

zdoc/ 必须与 site/ 同级，最终应能找到 zdoc/www/index.php 。请避免解压到 site/ 内，或形成 zdoc/zdoc/ 的重复目录。

3.2 解压程序包

将适配的 zdoc 程序包上传到服务器。以下以 /path/to/zdoc-22.6-php8.4.zip 为例，请将该路径替换为实际安装包路径。

unzip -q /path/to/zdoc-22.6-php8.4.zip
ls zdoc/www/index.php

3.3 设置目录权限

zdoc 运行时需要向以下目录写入内容：

zdoc/tmp ：缓存、日志、模板等文件。
zdoc/www/data ：上传的附件。

这两个目录必须对运行 xxd 的用户可写。如果使用运行 xxd 的同一账号解压，通常无需额外处理；如果使用 root 解压、xxd 由其他用户运行，则需要调整所属用户和权限。

以下 xxduser 和 xxdgroup 为示例，请替换为实际运行 xxd 的用户和用户组，并以具有相应权限的账号执行：

chown -R xxduser:xxdgroup zdoc
chmod -R u+rwX zdoc/tmp zdoc/www/data

四、导入 xxb 的配置与授权

4.1 创建安装脚本

在 xxd 根目录创建 install.sh ，使其与 site/ 、zdoc/ 同级，并写入以下内容：

#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")"
cp -f site/config/my.php zdoc/config/my.php
if [ -n "$(tail -c 1 zdoc/config/my.php)" ]; then echo >> zdoc/config/my.php; fi
if ! grep -q '^\$config->webRoot' zdoc/config/my.php; then
    echo '$config->webRoot     = getWebRoot();' >> zdoc/config/my.php
fi
if ! grep -q "requestType[[:space:]]*=[[:space:]]*'GET'" zdoc/config/my.php; then
    echo "\$config->requestType = 'GET';" >> zdoc/config/my.php
fi
if [ -f site/config/license/xxb.php ]; then
    cp -f site/config/license/xxb.php zdoc/config/license/zentao.txt
else
    echo "ERROR: 未找到 site/config/license/xxb.php，请先完成 xxb 授权" >&2
    exit 1
fi

4.2 执行安装脚本

保存脚本后，在 xxd 根目录执行：

bash install.sh

脚本会复制 xxb 的配置文件，按需补充 zdoc 的访问配置，并将 xxb 授权文件复制为 zdoc 使用的 zdoc/config/license/zentao.txt 。

脚本可以重复执行，但每次都会覆盖 zdoc/config/my.php ，授权文件存在时也会覆盖 zdoc/config/license/zentao.txt 。如已有 zdoc 配置，执行前请先备份，执行后核对需要保留的自定义设置。若提示缺少授权文件，请先完成 xxb 授权，再重新执行脚本。

五、重启 xxd

xxd 在启动时检查并挂载 zdoc，因此完成程序放置、配置与授权导入后，需要重启 xxd。请根据实际部署方式选择对应命令。

5.1 独立包

以下以独立包部署目录 /opt/xxd 为例，请替换为实际目录：

cd /opt/xxd
./start.sh restart

如果已注册为名称为 xxd 的 systemd 服务，也可执行：

sudo systemctl restart xxd

5.2 一键包

sudo /opt/zbox/zbox restart

重启后，检查启动日志中的 ZDoc 相关提示，确认应用挂载情况。

六、访问与验证

6.1 从喧喧客户端进入

登录喧喧客户端后，进入“文档”。客户端会将 xxd 派发的 authToken 传递给 zdoc，完成单点登录。

6.2 浏览器地址说明

zdoc 的浏览器访问地址如下，地址中的服务器地址和端口请替换为实际值：

http://<服务器地址>:<adminPort>/zdoc/index.php

adminPort 以 config/xxd.conf 中的配置为准，默认值为 9080 。/zdoc/ 与 /zdoc/index.php 等价。

默认配置为 $config->sso->xxdOnly = true 。直接在浏览器中打开上述地址时，如果没有可用的 authToken ，将无法登录，这是正常现象。日常使用请从喧喧客户端进入。

6.3 功能检查

从喧喧客户端进入文档后，依次检查：

能正常打开文档首页和文档库列表。
能新建文档库和文档，数据正常写入 xxb_zt_doclib 、xxb_zt_doc 等相关文档表。
能正常上传附件；如上传失败，请检查 zdoc/www/data 的写入权限。
zdoc/tmp/log 下没有新增的 PHP 错误日志。