跳到主要内容
版本：Next

安装配置

如何配置极狐星TowerFox 和极狐GitLab 的 SSO​

极狐星TowerFox 支持 SSO ，可以通过极狐GitLab 实现登录。

注意： 这里极狐GitLab 仅仅做为一种注册登录极狐星TowerFox 的快捷手段，和极狐星TowerFox 1.x 版本不同，这不再是一个必需的操作，通过 SSO 方式创建的极狐星TowerFox 用户也和极狐GitLab 没有直接关系。

极狐GitLab 端​

配置极狐GitLab 端：

  1. 登录极狐GitLab，可以在"实例"、"群组"和"用户"三个层面配置极狐GitLab 为 OAuth provider。具体步骤可以参见官方文档。

需要注意以下两点：

  • 极狐星TowerFox 默认回调 URL 为 /api/auth/jihulab/callback。

    比如极狐星TowerFox 如果运行在 HTTP 协议下，该回调 URL 为：http://[TOWERFOX_DOMAIN]:[TOWERFOX_PORT]/api/auth/jihulab/callback；

    极狐星TowerFox 如果开启了 SSL，该回调 URL 为：https://[TOWERFOX_DOMAIN]:[TOWERFOX_HTTPS_PORT]/api/auth/jihulab/callback；

  • 需要申请开放的权限为 read_repository、read_user 和 api。

创建成功的信息如下所示：

application

  1. 保存 应用程序ID 和 密码。

极狐星TowerFox 端​

配置极狐星TowerFox 端：

  1. 在 "组织架构 > 实例管理" 中新建一个实例，确保其 "URL" 参数为 极狐GitLab 实际的 URL 地址，复选"作为快捷登录方式"后，填写如下两个参数：

  • OAuth Client Id：上一步中获得的 应用程序ID

  • OAuth Client Secret：上一步中获得的 密码

具体创建实例过程，可以参看实例管理章节。

  1. 保存退出，配置完成。

至此，您已全部完成极狐星TowerFox 和极狐GitLab 的 SSO 整合，将获得的 OAuth Client Id 和 OAuth Client Secret 配置在极狐星TowerFox 的实例中，可以用指定极狐GitLab 登录极狐星TowerFox。

配置极狐星TowerFox 的域名和端口​

在 install.env 中，修改 TOWERFOX_DOMAIN 和 TOWERFOX_PORT 就可以修改极狐星TowerFox 运行时的域名和端口，如果需要开启 SSL，请参见 配置 SSL

配置极狐星TowerFox 不同的 SSO 域名​

若极狐星TowerFox 实际访问 URL 和上述变量 TOWERFOX_DOMAIN 和 TOWERFOX_PORT 不一致，则会造成 SSO 登录失败，例如：

  1. 浏览器访问 https://tf.com，客户环境存在负载均衡器解析请求，将 https 转成 http 发到 http://tf.com:18080
  2. TOWERFOX_DOMAIN 配置成 tf.com，TOWERFOX_PORT 配置成 18080 才能正常响应请求
  3. SSO 过程中极狐星TowerFox 会根据请求 URL 生成 OAuth callback: http://tf.com/18080/some-callback
  4. 但在 gitlab 中配置的 callback url 是 https://tf.com/some-callback，这样会发生 OAuth 错误

在极狐星TowerFox v2.4.0，解决方法是在 install.env 中配置 TOWERFOX_OAUTH_EXTERNAL_HOST 环境变量，然后重新安装，确保极狐星TowerFox 生成的 OAuth callback 是 https://tf.com/some-callback，完成 OAuth 认证流程。若低于2.4.0 版本，请联系我们。

更改服务环境变量配置，重启服务后无效​

更改 TOWERFOX_BASE 中相关服务的环境变量，通过 tfctl restart service 命令重启服务后，没有生效。

更改 docker-compose 的 yml 文件后，仅仅 restart 服务是不会生效的，需要重新加载服务，比如更改 rails 服务的 SSO 配置。正确方法如下：

  1. 打开 /opt/towerfox/docker-compose.yml，更改 rails 中的如下三个环境变量：
    GITLAB_URL: 
    OAUTH_APPLICATION_ID: 
    OAUTH_SECRET:
  1. 重新加载 rails 服务。
tfctl reload

将极狐星TowerFox 开启 SSL 后，以 Oauth 登录方式报错 “The redirect URI included is not valid.”​

极狐星TowerFox 运行在 HTTP 模式下一切正常，但按照文档开启 SSL 后，只能以“用户名/密码”的方式登录；如果以 Oauth 方式登录，会在极狐GitLab 界面报错 The redirect URI included is not valid.。

该问题是由在极狐GitLab 中配置的回调地址不正确导致的。

极狐星TowerFox 运行在 HTTP 模式下，回调地址是 HTTP 协议，此时运行正常；但开启 SSL 后，极狐GitLab 通过之前 HTTP 的回调地址将无法正常调用成功，导致 Oauth 登录失败，此时需要将极狐GitLab 侧定义的极狐星TowerFox 的 Oauth 回调地址更改为 https 协议。具体可参看配置 SSO 章节。

以 Oauth 方式登录后，在授权同意弹出框中选择"授权"，但依然提示"您拒绝授权，无法完成登录"​

对于极狐星TowerFox v1.6.2 之前的版本，如果对接的极狐GitLab 开启了 SSL，并且使用了自签名证书（比如非认证 CA 机构签发的证书），那么这是一个已知 bug，解决方法有以下 2 种：

  1. 升级极狐星TowerFox 到 v1.6.2 及以上版本。
  2. 对接的极狐GitLab 使用认证 CA 机构签发的证书。

对于极狐星TowerFox v1.6.2 以上的版本，该情况要具体问题具体分析，查看极狐星TowerFox 日志以确定问题根源（默认日志位于: /opt/towerfox/api/logs 目录），常见错误包括但不限于：

  1. 极狐GitLab 域名无法解析。
  2. 极狐GitLab 接口调用超时。
  3. oauth 其他错误。

如何配置极狐星TowerFox 的 Sidekiq 个数和资源约束​

对于 Compose 安装方式来说，所有组件都运行在一个主机节点，当工作负荷较大时（比如在极狐星TowerFox 上创建的 org 关联了较大的极狐GitLab 群组），需要配置合适的 Sidekiq 数目，确保系统效率的同时保证主机稳定。

可通过如下两个配置加快极狐星TowerFox 的数据处理速度：

TOWERFOX_DATA_EXTRACTOR_COUNT 极狐星TowerFox 启动的用于处理任务的 sidekiq 服务个数，这些任务包括数据抽取和历史数据统计等，默认为 1。

TOWERFOX_SIDEKIQ_CONCURRENCY 每个 sidekiq 进程可以并行运行的线程个数，默认为 10。

比如如下配置:

TOWERFOX_DATA_EXTRACTOR_COUNT=3
TOWERFOX_SIDEKIQ_CONCURRENCY=20

那么，最多就会有 3*20=60 个并发线程进行数据抽取和处理，极大提升极狐星TowerFox 的数据处理速度和吞吐率。

但需要注意：想要处理的数据较多时，长时间运行，依然有可能会耗尽主机资源。

此时通过如下配置来对每个 sidekiq 服务所能使用的资源进行限制：

TOWERFOX_SIDEKIQ_MEMORY_LIMIT 每个 Sidekiq 服务允许使用的最大内存量（单位 m，gb），最小为 500 m。

如果这个 sidekiq 进程使用的 memory 资源超过指定内存用量，进程会被杀掉（之后自动重启），以确保主机资源不会被耗尽。

注意： 这个数值的设置需要根据极狐星TowerFox 所在主机的实际 memory 情况进行设置，比如按照如下原则计算：（[主机总Memory]-4GB）/[sidekiq count]

如何配置极狐星TowerFox 的 Redis 参数​

Redis 在极狐星TowerFox 中同时起着缓存和临时数据库的作用。系统的 session 和 Sidekiq 任务处理队列等都依赖于 Redis。正常情况下，Redis 不会耗费太多资源，但在个别情况下，Redis 同样会消耗较多资源，如果参数配置错误，会导致出现异常，比如系统访问缓慢和数据丢失等。

当在极狐星TowerFox 上创建的群组关联了较多的极狐GitLab 项目/群组时，会触发大量的数据抽取任务。如果此时并行运行的 Sidekiq 服务较多（参见 Sidekiq配置），那么就给 Redis 带来较多资源压力，主要表现在内存消耗剧增。极端情况下，会耗尽主机资源，影响极狐星TowerFox 的可用性。

极狐星TowerFox 默认配置下，Redis 资源原则如下：

  1. Redis 容器可以使用主机的所有资源，包括 CPU 和 Memory。
  2. Redis 应用的 maxmemory 为 800 MB，即最多使用 800 MB 的内存资源。超过这个数目，将会触发内存淘汰机制，释放资源。
  3. Redis 的内存淘汰机制为 volatile-lru，即按照 LRU 原则，淘汰 Redis 中没有设置过期时间的 key 值。

上述默认 Redis 的配置可通过如下方式更改：

  • Docker-Compose 安装方式，直接更改 <towerfox运行目录>/redis/redis.conf 文件，然后重启 Redis 容器服务即可。
  • Helm Chart 安装方式，更改 value.yml 中 redis.master.extraFlags 下的参数，然后更新服务即可。

极狐星TowerFox 初始安装配置是通过 IP 地址访问，如何能在不重新安装的情况下，更改为以域名方式访问？​

具体步骤如下：

1. 极狐星TowerFox 方面

`/opt/towerfox/.env` 里的 `TOWERFOX_DOMAIN` 字段从 `ip` 改为域名；`TOWERFOX_HOST` 字段中的 `ip` 也改为域名。

`/opt/towerfox/nginx/includes/https.d/` 目录下 `*.conf` 文件中的 `server_name` 改为对应的域名。

然后手动重新加载重启极狐星TowerFox 服务：`tfctl reload`。

2. 极狐GitLab 方面

更改在极狐GitLab 中配置的用于 oauth 登录的 towerfox callback 地址，需要把 ip改为域名，否则后续就无法用 oauth 方式登录。

比如：

http://192.168.22.14/api/auth/jihulab/callback    更改为
http://[towerfox_domain_name]/api/auth/jihulab/callback

极狐星初始安装配置是未开启 SSL 的，如何更改为开启 SSL 方式访问？​

将 http 更改为 https，涉及到证书/私钥等文件的配置更改，手动更改较麻烦。推荐先卸载极狐星TowerFox，更改 install.env 文件，然后安装，步骤如下：

1. 更改 `install.env`，开启 `TOWERFOX_SSL_ENABLED`， 并指定 ca 证书和私钥文件，类似如下：

TOWERFOX_SSL_ENABLED=true
TOWERFOX_SSL_CERT=/tmp/mycerts/domain.crt
TOWERFOX_SSL_CERT_KEY=/tmp/mycerts/domain.key

2. 检查确保 `install.env` 中的 `TOWERFOX_DOMAIN` 和提供的 ca 证书文件中的 `common name` 一致！

3. 执行 `install.sh` 文件，进行极狐星TowerFox 安装。

4. 在极狐GitLab 端，更改极狐星TowerFox 的 callabck 地址，将 `http` 更改为 `https`。

如果不希望重新安装极狐星TowerFox，直接在现有极狐星TowerFox 系统之上开启 ssl，步骤略微复杂。

比如将 http://testtf.gitlab.cn:80 更改为 https://testtf.gitlab.cn:443，对应的 ca 证书和私钥文件位于当前主机的 /tmp/mycerts/domain.crt 和 /tmp/mycerts/domain.key，具体步骤参考如下：


1. 更改**极狐星TowerFox 工作目录**下的 `.env` 文件，默认为 `/opt/towerfox/.env`。

TOWERFOX_SSL_CERT=/tmp/mycerts/domain.crt
TOWERFOX_SSL_CERT_KEY=/tmp/mycerts/domain.key
TOWERFOX_SSL_ENABLED=true

检查如下两个参数：

TOWERFOX_DOMAIN=testtf.gitlab.cn
TOWERFOX_HOST=https://testtf.gitlab.cn:443

2. 拷贝 ssl 证书和私钥文件到**极狐星TowerFox 工作目录**（默认为 `/opt/towerfox`）。

将 `/tmp/mycerts/domain.crt` 和 `/tmp/mycerts/domain.key` 拷贝到 `/opt/towerfox/nginx/certs/` 目录下，并更改名字为 `towerfox.crt"和“towerfox.key`。

cp /tmp/mycerts/domain.crt /opt/towerfox/nginx/certs/towerfox.crt
cp /tmp/mycerts/domain.key /opt/towerfox/nginx/certs/towerfox.key

3. 增加 nginx 相关 ssl 配置项目。

将极狐星TowerFox 安装目录下的 `towerfox/nginx/includes/https.d/ssl.conf` 拷贝到 `/opt/towerfox/nginx/includes/https.d/`。

将 `/opt/towerfox/nginx/includes/ssl.conf` 里的 `_TOWERFOX_DOMAIN` 和 `_TOWERFOX_HTTPS_PORT` 两个变量替换为域名和 `https` 端口， 即 `testtf.gitlab.cn` 和 `443`。

将极狐星TowerFox 安装目录下的 `towerfox/nginx/includes/servers.d/server.conf` 拷贝到 `/opt/towerfox/nginx/includes/servers.d/`。

将 `/opt/towerfox/nginx/includes/server.conf` 里的 `_TOWERFOX_DOMAIN` 和 `_TOWERFOX_PORT` 两个变量替换为域名和 `http` 端口，即 `testtf.gitlab.cn` 和 `80`。

删除 `/opt/towerfox/nginx/includes/https.d/nonssl.conf`。

4. 执行 `tfctl reload`，使环境变量更改生效。

5. 重启 nignx 容器服务，使得 ssl 配置在 nginx 层面生效。
 
此时，当前极狐星TowerFox 实例已经开启 https 服务，可以通过 `https://testtf.gitlab.cn` 或者 `http：//testtf.gitlab.cn` 访问。

但现在还不能以 oauth 方式访问极狐星TowerFox，需要再更改极狐GitLab 中的 `oauth callback`。

6. 更改极狐GitLab 中配置的 `towerfox callback` 地址，将 `http` 协议更改为 `https`，如下：

http://testtf.gitlab.cn/api/auth/jihulab/callback  改为  https://testtf.gitlab.cn/api/auth/jihulab/callback

至此，更改配置结束。

极狐星TowerFox 开启 SSL 后，审计事件页面不再有新审计记录产生​

该问题一般由两种情况导致：

  • 极狐星TowerFox 开启 SSL 后，在极狐GitLab 的顶级群组中创建的审计事件流 URL 也需要更改为 https 协议，否则极狐GitLab 无法将新产生的审计事件推送到极狐星TowerFox 中。如下截图所示：

streamURL

  • 极狐星TowerFox 开启 SSL 使用的是自签名证书，且没有配置极狐GitLab 信任该证书，导致新审计信息推送失败。

自签名证书一般用于测试，如果没有配置信任该自签名证书，在调用时会有如下报错（以 curl 调用为例）：

curl: (60) SSL certificate problem: self signed certificate
More details here: https://curl.haxx.se/docs/sslcerts.html

curl failed to verify the legitimacy of the server and therefore could not
establish a secure connection to it. To learn more about this situation and
how to fix it, please visit the web page mentioned above.

curl 调用可以通过添加 “-k” 参数忽略该错误，但对于极狐GitLab 的审计事件流来说，此方法无效。需要在极狐GitLab 实例上配置 SSL 信任极狐星TowerFox 使用的自签名证书。对于采用 Omnibus 方式安装的极狐GitLab，可参考安装自定义证书。

执行安装脚本时，以哪个文件中定义的变量为准？是安装目录的 install.env 还是运行目录的 .env (默认为 /opt/towerfox/.env)？​

极狐星TowerFox 的安装脚本，即 install.sh，是可以执行多次的。

  • 如果是初始安装，此时并没有运行目录的 .env 文件(/opt/towerfox/.env)，因此这种情况下按照安装目录下 install.env 中定义的变量为准。

  • 如果不是初始安装，而是运行一段时间后，再次执行安装脚本，则此时安装脚本选择安装配置参数的逻辑如下：

    • 合并 install.env 和运行目录下 .env（/opt/towerfox/.env）内容。
    • 如果有同名变量，那么以运行目录下 .env 文件（/opt/towerfox/.env）定义的变量为准。
    • 据此生成新的 .env 文件，保存为 /opt/towerfox/.env。
    • 根据最新变量情况，进行服务安装。

NOTE: 安装目录下的 install.env 是初始配置文件。安装后，里面的内容不会对运行的极狐星TowerFox 实例产生影响。

运行目录下的 .env 文件保存的变量才是当前运行的极狐星TowerFox 实例所真正使用的。如果要更改极狐星TowerFox 参数，需要 .env 文件，然后执行 tfctl reload。

执行升级脚本时，以哪个文件中定义的变量为准？是安装目录的 install.env 还是运行目录的 .env (默认为 /opt/towerfox/.env)？​

选择把当前运行的极狐星TowerFox 从 v1.6.0 升级到 v1.7.0 时，v1.7.0 安装目录中的 install.env 文件（比如 v1.7.0/install.env）、v1.6.0 安装目录中的 install.env 文件 (比如 v1.6.0/install.env) 和 v1.6.0 运行目录下的 .env (比如 /opt/towerfox/.env)文件，这三个文件中定义的变量是哪个在起作用？

在进行极狐星TowerFox 升级时，系统变量的选择遵循如下逻辑（以上述情况为例）：

  • 老版本安装目录下的 install.env 不再起任何作用，即不再考虑 v1.6.0/install.env 里面的内容。
  • 老版本运行目录下的 .env 文件中已有的内容不变，即 /opt/towerfox/.env 现有内容不变。
  • 将新版本的新增字段添加到老版本运行目录下的 .env 中，即 v1.7.0/install.env 中存在有，但 /opt/towerfox/.env 中没有的字段，添加到 /opt/towerfox/.env 中。
  • 据此生成新的 .env 文件，保存为 /opt/towerfox/.env。
  • 根据最新变量情况，执行后续服务更新。

极狐GitLab 打开效能分析开关（针对极狐星TowerFox v1.5 版本之前）​

极狐星TowerFox 主要使用极狐GitLab 的 API 来获取相关效能信息，其中用到了极狐GitLab 专业版的效能分析接口来获取项目和群组的相关统计信息，使用该接口有如下要求：

  • 极狐GitLab 版本大于等于 15.4、15.2.5 或 15.3.4。
  • 开启效能分析的功能标志，具体请参见开启效能分析文档。步骤过程如下：
  1. 在命令行运行 gitlab-rails console 命令进入 console 模式。
  2. 运行 Feature.enable(:performance_analytics)，启用效能分析功能开关。
    root@VM-5-29-ubuntu:~# gitlab-rails console
--------------------------------------------------------------------------------
 Ruby:         ruby 2.7.5p203 (2021-11-24 revision f69aeb8314) [x86_64-linux]
 GitLab:       15.4.0-jh (a4871463f19) EE
 GitLab Shell: 14.10.0
 PostgreSQL:   13.6
------------------------------------------------------------[ booted in 27.44s ]
Loading production environment (Rails 6.1.6.1)
irb(main):001:0> Feature.enable(:performance_analytics)
WARNING: Understand the stability and security risks of enabling in-development features with feature flags.
See https://docs.gitlab.com/ee/administration/feature_flags.html#risks-when-enabling-features-still-in-development for more information.
=> true