禅道配置与使用小记

准备试试禅道，简单记录一下。

注意，本文提到的禅道，指代禅道开源版18.11。

安装

禅道有提供Linux下的一键安装包，也有用于Debian和Ubuntu的Deb包。

安装后,apache的配置文件位于：

/opt/zbox/etc/apache/httpd.conf

在该文件内，可以修改监听地址等，比如：

Listen 127.0.0.1:81

以便于配置nginx作为反向代理。

php配置文件位于

/opt/zbox/etc/php/php.ini

在该文件内，通过log_errors设置成on，可以启用日志记录。路径在/opt/zbox/logs/php_error_log.

另外，配置文件/opt/zbox/app/zentao/config/my.php中 $config->debug，也用于配置日志。日志目录位于 /opt/zbox/app/zentao/tmp/log

一些命令

启动：/opt/zbox/zbox/start
停止：/opt/zbox/zbox stop
重启：/opt/zbox/zbox restart
检查：/opt/zbox/zbox check

ZBOX是禅道官方在linux下面运行的apache, php, mysql一键安装包。

插件学习

禅道的扩展系统，从16.5版本起，其行了比较大的重构。

感觉上，对插件开发挺不友好的，官方文档似乎很不全，第三方插件少，可能我没找到原因

基本机制

禅道有一个个的模块组成：

project
user
admin
product
job
...

每个模块又按照mvc进行划分M V C三层和辅助config、lang、css、js：

control：控制层
model：模型层
view：视图层
config：配置
lang：语言
css：样式
js：脚本

对已有模块扩展（直接在对应ext目录下）：

extension/custom/user/ext/control/{method1.php, method2.php, ...} 
extension/custom/user/ext/model/{extend1.php, extend2.php, ...}
extension/custom/user/ext/view/{method1.html.php, method2.html.php, ...}
extension/custom/user/ext/config/{config1.php, config2.php, ...}
extension/custom/user/ext/lang/zh-cn/{lang1.php, lang2.php, ...}
extension/custom/user/ext/lang/en/{lang1.php, lang2.php, ...}
extension/custom/user/ext/css/method1/{1.css, 2.css, ...}
extension/custom/user/ext/js/method1/{1.js, 2.js, ...}

对新的模块，都在extension目录下。包含ext外的基本文件，和ext下的的扩展文件：

extension/custom/oa/control.php
extension/custom/oa/model.php
extension/custom/oa/view/{metho1.html.php, method2.html.php, ...}
extension/custom/oa/config/config.php
extension/custom/oa/css/{method1.css, method2.css, common.css, ...}
extension/custom/oa/js/{method1.js, method2.js, common.js, ...}

extension/custom/oa/ext/control/{method1.php, method2.php, ...} 
extension/custom/oa/ext/model/{extend1.php, extend2.php, ...}
extension/custom/oa/ext/view/{method1.html.php, method2.html.php, ...}
extension/custom/oa/ext/config/{config1.php, config2.php, ...}
extension/custom/oa/ext/lang/zh-cn/{lang1.php, lang2.php, ...}
extension/custom/oa/ext/lang/en/{lang1.php, lang2.php, ...}
extension/custom/oa/ext/css/method1/{1.css, 2.css, ...}
extension/custom/oa/ext/js/method1/{1.js, 2.js, ...}

打包规范

需要一个doc目录。不知道怎么回事，越看越看不懂，特别是releases...

doc目录下面包含了插件的配置信息，按照语言进行存储，比如英文版本的，存为en.yaml，中文zh-cn.yaml

插件的配置文件采用yaml格式，里面包含了插件的基本信息以及历次版本的发布信息。

新建模块

按照zentaoPHP框架结构，在插件目录(extension/custom)下创建子目录，比如ldap，然后，按照预定，分别实现对应的control，model，view，css，js，lang等概念。

比如ldap插件，在extension/custom/ldap目录下：

.
├── config.php
├── control.php
├── css
│   └── setting.css
├── js
│   └── setting.js
├── lang
│   ├── en.php
│   ├── zh-cn.php
│   └── zh-tw.php
├── model.php
└── view
    └── setting.html.php

对比官网说法，这个插件的config.php位置似乎有问题，应该在 config/config.php 下？，不过官方extension之外的标准模块，config.php都是直接用的。

对model扩展

前面的ldap模块，对user的model层进行了扩展，extension/custom/user

.
└── ext
    ├── config
    │   └── config.php
    └── model
        ├── identify.php
        └── updatePassword.php

禅道有多种方法扩展model层。此处是通过在 ext/model/ 目录下面建立相应的 以方法为名的文件。

禅道框架在执行的时候，会自动将扩展目录下面的identify.php里面的代码，替换misc/model.php中的identify方法的代码。如果是新增的方法，则会追加到misc/model.php的代码中，最终生成一个合并之后的model类文件。

对语言扩展

语言的扩展文件存放在ext/lang/ 目录下面。按照不同的语言建立相应的目录，比如zh-cn下面，可以有多个文件，zentaoPHP框架会 自动加载该目录下面所有以.php结尾的文件。

比如 Ldap，对admin模块进行扩展，在extension/custom/admin下:

.
└── ext
    └── lang
        ├── de
        │   └── ldapauth.php
        ├── en
        │   └── ldapauth.php
        ├── fr
        │   └── ldapauth.php
        ├── zh-cn
        │   └── ldapauth.php
        └── zh-tw
            └── ldapauth.php

对配置扩展

每个模块配置文件的扩展文件存放在 ext/config/ 目录下面，可以有多个文件，zentaoPHP框架会自动加载该目录下面以config开头的.php文件。这样不同的扩展可以有自己的配置项，彼此之间不会冲突。

在前面的 `extension/custom/user``下，可以配置的扩展（文件名无所谓）：

.
└── ext
    ├── config
    │   └── config.php
    └── model
        ├── identify.php
        └── updatePasswo

配置

nginx 配置

可以使用nginx作为反向代理，以便于引入ssl支持等，简单配置一下：

# server configuration for gitlab
server {

        listen 443 ssl;

        server_name projects.debao.me;

        ssl on;
        ssl_certificate /etc/ssl/projects.debao.me.cer;
        ssl_certificate_key /etc/ssl/projects.debao.me.key;

        location = / {
                return 301 https://projects.debao.me/zentao/user-login-L3plbnRhby8=.html;
        }

        location / {
                proxy_pass http://127.0.0.1:81;

                # Allow for large file uploads
                client_max_body_size 0;

                proxy_set_header Host $http_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;
        }
}

注意：配置行 proxy_set_header X-Forwarded-Proto $scheme;很关键，不然用户在https模式下无法登录。

这是因为在文件/opt/zbox/zbox/app/zentao/framework/base/router.class.php中，有如下处理CSRF的代码。网上不少人遇到的https无法登录的问题，给出的方案就是：直接注释掉它们。这也...太简单粗暴了。

        /* Change for CSRF. */
        if($this->config->framework->filterCSRF)
        {
            $httpType = (isset($_SERVER["HTTPS"]) && $_SERVER["HTTPS"] == 'on') ? 'https' : 'http';
            if(isset($_SERVER['HTTP_X_FORWARDED_PROTO']) and strtolower($_SERVER['HTTP_X_FORWARDED_PROTO']) == 'https') $httpType = 'https';
            if(isset($_SERVER['REQUEST_SCHEME']) and strtolower($_SERVER['REQUEST_SCHEME']) == 'https') $httpType = 'https';

            $httpHost = zget($_SERVER, 'HTTP_HOST', '');
            $apiMode  = (defined('RUN_MODE') && RUN_MODE == 'api') || isset($_GET[$this->config->sessionVar]);
            if(!$apiMode && (empty($httpHost) or strpos($this->server->http_referer, "$httpType://$httpHost") !== 0)) $_FILES = $_POST = array();
        }

另外location = /配置行，只为了直接跳转到登录页面，而不是停留在默认的广告界面，在手动点击登录开源版本。

除此之外，在局域网内，可以设置根据主机名或者非ssl端口，直接进行跳转到ssl端口（配置文件加入如下若干行）：

server {
    listen 80;
    server_name projects projects.debao.me;
    return 301 https://projects.debao.me$request_uri;
}

server {
    listen 443;
    server_name projects
    return 301 https://projects.debao.me$request_uri;

Ldap配置

禅道官方没有给开源版提供Ldap支持。官网有如下一个链接，只支持到禅道7.3版本，早过时了。

禅道开源版LDAP插件 - 版本详情 - 禅道开源项目管理软件 (zentao.net)

在Github有不少用于禅道的LDAP插件：

东西最多，但一眼看去，感觉都不太靠谱...，

尝试1

先试试第一个 twoBxx/zentao-ldap-plugin，下载后，做成zip压缩包 ldap.zip (不包含顶层目录）。

插件安装

在界面等登陆后，通过 后台->插件管理 调出插件管理界面。

选中前面的 ldap.zip，强制安装（因为版本不完全匹配）。

安装后到 后台->系统设置->LDAP页面进行配置

LDAP配置

选项	示例值	必填	默认值
基础配置
协议	ldap://，ldaps://	T	ldap://
LDAP服务器	ldap.test.com	T
端口	389，636	T
searchDN	ou=users,dc=test,dc=com	T
BindDN	cn=admin,dc=test,dc=com	T
BindDN 密码	ou=users,dc=test,dc=com	T
属性配置
账号字段	uid/sAMAccountName	T	uid
默认用户组	下拉选择	F	管理员
Mail	mail	F	mail
姓名字段	cn	T	cn
手机号	mobile	F	mobile

界面修改的配置，写入到文件extension/custom/ldap/config.php 中。

保存操作位于extension/custom/ldap/control.php中

注意，由于ldap_get_entries() 返回的数组中所有键名都是小写的，所以uid设置samaccountname也应该都用小写字符。

问题：ldap连接测试不过

找到一个bug

extension/custom/ldap/control.php 文件内，sssList在lang中而不是config中：

 public function test()
 {
      $fh = $this->config->ldap->sslList[$this->post->ssl] . $this->post->host . ':' .$this-    >post->port;

改为：

 public function test()
 {
      $fh = $this->lang->ldap->sslList[$this->post->ssl] . $this->post->host . ':' .$this-    >post->port;

非tsl下的连接测试通过。

问题：任然无法同步账户

使用ldap和389端口，ldap连接没问题。

但是Ldap用户还是无法登录，可能和用的 uid 取的 'sAMAccountName' 有关（改写全小写samaccountname）没有改善。

排查extension/custom/ldap/model.php，由于AD中不是所有用户都配置了email和mobile字段，需要确保这两个字段不为null：

        for (; $i < $ldapUsers['count']; $i++) {
            $user->account = $ldapUsers[$i][$config->uid][0];
            $user->realname = $ldapUsers[$i][$config->name][0];
            // 确保 mobile 字段不为 NULL
            $user->email = !empty($ldapUsers[$i][$config->mail][0]) ? $ldapUsers[$i][$config->mail][0] : $user->realname . "@debao.me";
            $user->mobile = !empty($ldapUsers[$i][$config->mobile][0]) ? $ldapUsers[$i][$config->mobile][0] : "12345678";

手动同步账户通过。

问题：LDAP账户依然无法登录

需要排查 extension/custom/user/ext/model/identify.php

...

问题：tls

但是ldaps和 636默认还是不行。可能和证书不受信任有关。用ldapsearch进行测试。

尽管忽略证书校验，使用ldapsearch没问题

ldapsearch -H ldaps://dc1.debao.me:636 -x -D "cn=admin,dc=debao,dc=me" -w your_password -b "dc=debao,dc=me" -o "tls_reqcert=never"

尝试2

试试 luzi2000/zentao-ldap

很顺利