禅道从20.1版本开始，为了提升性能，开启了数据缓存功能，因此PHP需要安装APCu扩展。本文针对一键安装包和源码安装的禅道介绍了安装APCu扩展的方法。

一、基于一键安装包安装的禅道

1.1、Linux一键安装包

1.1.1 源码编译安装APCu扩展

为了最大限度的兼容本机环境，推荐通过本地编译的方式来安装扩展，如果不想本地编译，请参考1.2，下载我们编译好的扩展。

编译安装APCu扩展

# 切换到临时目录
cd /tmp

# 下载源码包
wget https://pecl.php.net/get/apcu-5.1.23.tgz

# 解压，编译
 tar xvzf apcu-5.1.23.tgz
 cd apcu-5.1.23
 /opt/zbox/run/php/phpize ./configure  --with-php-config=/opt/zbox/run/php/php-config
 make && make install

# 如果没有报错，查看扩展是否安装成功
ls -l /opt/zbox/run/php/extensions/apcu.so 

配置APCu扩展

# 写入配置
cat >> /opt/zbox/etc/php/conf.d/apcu.ini << EOF
[apcu]
extension = apcu.so
apc.shm_size = 1024M
EOF

# 查看配置是否写入成功
/opt/zbox/etc/php/conf.d/apcu.ini

校验配置是否有效

/opt/zbox/bin/php -m | grep apcu
apcu

1.1.2 下载编译的APCu扩展

为了方便Linux系统一键安装包用户快速配置扩展，我们提供了编译好的APCu扩展，该扩展只支持 PHP 8.1：

# 下载并解压
curl -sl http://dl.zentao.net/zbox/runtime/php/8.1/exts/apcu-5.1.23-php-8.1.28-amd64.tar.gz | tar xvz -C /opt

# 验证安装是否成功
/opt/zbox/bin/php -m | grep apcu
apcu

# 重启apache服务
/opt/zbox/bin/apachectl -k restart

1.2、Windows一键安装包

下载APCu扩展文件

php8.x对应下载链接：https://downloads.php.net/~windows/pecl/releases/apcu/5.1.23/php_apcu-5.1.23-8.1-ts-vs16-x64.zip
其他php版本:  https://downloads.php.net/~windows/pecl/releases/apcu/

解压到指定位置

解压 php_apcu-5.1.23-8.1-ts-vs16-x64.zip 压缩包内的 php_apcu.dll 文件到 ZenTao\bin\php\ext\ 目录下。

配置参数

修改文件 ZenTao\etc\php\php.ini ，增加内容：

extension=php_apcu.dll

[apcu]
apc.shm_size=1024M

验证

打开cmd，进入 ZenTao\bin\php 目录，输入：

.\php.exe -m | find "apcu"

如果有 apcu 的输出，则证明可以正常加载。

二、源码安装的禅道

2.1 Linux系统

编译安装APCu扩展

# 切换到临时目录
cd /tmp

# 下载源码包
wget https://pecl.php.net/get/apcu-5.1.23.tgz

# 解压，编译
 tar xvzf apcu-5.1.23.tgz
 cd apcu-5.1.23
 </你本地的/phpize>  ./configure  --with-php-config=<你本地的/php-config>
 make && make install

注意：
- 将  </你本地的/phpize> 替换为你本地 phpize 命令的实际路径
- 将  <你本地的/php-config> 替换为你本地 php-config 命令的实际路径
- apcu 5.1.23 只支持PHP 8.x以上版本，如果是PHP 7.x 请选择 apcu 5.1.21

配置APCu扩展

# 写入配置
cat >> <你本地的php.ini文件> << EOF
[apcu]
extension = apcu.so
apc.shm_size = 1024M
EOF

将  <你本地的php.ini文件>  替换为你本地的 php.ini 实际目录

校验配置是否有效

php -m | grep apcu
apcu

2.2 Windows系统

请访问 [https://phpext.phptools.online/] 下载适合你PHP版本的APCu扩展。

三、禅道系统中启用/关闭数据缓存

禅道 20.1.0 基于 PHP-APCu 实现了数据缓存功能，使用该功能需要加载 PHP-APCu 扩展。
数据缓存功能主要应用于读取数据的场景，开启后页面加载速度显著提高。根据测试，在不同的使用场景下能为系统带来 10-50 倍的性能提升。

3.1 安装

安装过程中会检查是否开启了 PHP-APCu 扩展，如果加载并且启用了 apc.enabled 选项，安装完成后会自动打开数据缓存功能。

在【后台】->【人员管理】->【权限】中增加了缓存的权限。

有权限的用户在【后台】->【系统设置】->【缓存】页面可以开启、关闭或清除缓存。

开启数据缓存时会检查是否加载了 PHP-APCu 扩展并且启用了 apc.enabled 选项，如果检查未通过会弹出相关提示。

开启或关闭缓存均会清空已缓存的数据，以防止缓存命中过期数据。

3.2 升级

升级过程中会检查是否加载了 PHP-APCu 扩展并且启用了 apc.enabled 选项，如果检查通过会自动打开数据缓存功能。

3.3 使用

数据缓存功能是否开启对于用户来说是无感的，使用时没有任何不同。禅道系统会自动选择从缓存或者数据库中加载数据。

3.4 配置

您可以在 PHP 配置文件中使用 apc.shm_size 选项设置 APCu 功能可用的内存大小，默认为32M 。内存过小会导致缓存数据频繁更新从而影响性能，建议该选项尽可能设置大一些。

3.5 原理

禅道在 DAO 层封装了数据缓存逻辑。当使用 DAO 查询数据（fetch()、fetchAll()、fetchPairs()、fetchGroup()）时会优先从缓存中查询，如果缓存未命中则从数据库中查询并将查询结果放入缓存。当使用 DAO 更新数据（exec()）时，会将本次更新涉及到的表标记为缓存过期，从而实现缓存更新的功能。如果您使用 DBH 直接操作 SQL 语句的方式读取或更新数据，则无法使用数据缓存功能。

3.6 清除缓存

如果遇到缓存命中过期数据的情况，请联系我们。您也可以手动清除缓存，目前没有提供清除单个缓存的功能，您可以重启 php 或者在禅道后台关闭缓存后重新开启。