TCA 代码分析平台私有化部署踩坑实录：从零到跑通的十四场硬仗

如果你也在折腾 TCA（腾讯代码分析）平台的私有化部署，这篇文章可能能帮你少走不少弯路。从环境配置、容器启动、数据库连接，到文件服务器认证、数据格式兼容，我踩了一个又一个坑，最后终于跑通了。这篇文章把整个过程完整记录下来，希望对同样在部署 TCA 的朋友有所帮助。

前言

TCA（Tencent Code Analysis）是腾讯开源的代码分析平台，支持代码规范、重复代码、圈复杂度等多种分析维度。功能很强大，但私有化部署的坑也不少，它的开源仓库地址是：GitHub - Tencent/CodeAnalysis: Static Code Analysis - 静态代码分析 · GitHub

我按照官方文档一步步部署，以为能顺利跑起来，结果遇到一连串的问题：从 BOM 字符导致配置解析失败，到数据库密码格式错误，再到文件服务器认证、数据格式兼容......

这篇文章不是什么高深的技术分享，就是一份完整的踩坑实录。一共十四场硬仗，咱们从头说起。

第一阶段：部署启动 ------ 最基础的问题也是最烦人的

第一场：节点资源找不到 ------ 工具没地方跑

问题现象

刚部署完，创建代码分析任务，直接报：

复制代码

当前项目配置的运行环境标签[Codedog_Linux]没有机器资源可以运行工具[cpd(None);lizard(None);codecount(None)]

意思是没有机器注册到这个标签下，工具找不到执行环境。

排查思路

TCA 的执行架构是"主节点 + 分析节点"，分析节点需要注册并关联标签，主节点才能把任务分配过去。

解决方案

在分析节点上执行注册操作，把节点关联到 Codedog_Linux 标签：

确认节点服务已启动
在节点管理页面注册节点
给节点添加 Codedog_Linux 标签

注册成功后，工具就能找到执行环境了。

第二场：docker-compose.yml 有 BOM 字符 ------ 配置解析失败

问题现象

启动容器时，环境变量怎么都不生效。明明在 .env.local 里配置了各种参数，容器里却读不到。

排查思路

环境变量不生效，可能是 docker-compose.yml 解析有问题。用编辑器打开一看，文件开头有个奇怪的符号 ------ BOM 字符！

BOM（Byte Order Mark）是 UTF-8 编码的一个特殊标记，有些编辑器会自动加上，但 docker-compose 解析 YAML 时不认这个，导致整份配置文件解析失败。

解决方案

用 PowerShell 去掉 BOM 字符：

powershell 复制代码

(Get-Content docker-compose.yml -Raw) -replace "^" | Set-Content docker-compose.yml -NoNewline

去掉 BOM 后，重新启动容器，环境变量终于生效了。

第三场：页面空白 + 502 Bad Gateway ------ 容器没启动成功

问题现象

访问 Web 页面，直接空白，浏览器还报 502 Bad Gateway。

排查思路

502 意味着 Nginx 代理失败了。检查一下后端容器状态：

powershell 复制代码

docker ps

发现 main-server 容器根本没在运行！

找到真凶

查看容器日志：

powershell 复制代码

docker logs codeanalysis-main-main-server-1

日志显示数据库连接失败，容器启动就挂了。

第四场：数据库连接失败 ------ 密码格式坑人

问题现象

main-server 容器启动失败，日志报：

复制代码

Access denied for user 'root'@'mysql'

数据库密码认证失败。

排查思路

密码明明是对的，怎么会认证失败？仔细检查 .env.local 文件：

env 复制代码

MAIN_DB_PASSWORD='TCA!@#2021'

好家伙，密码周围有单引号！Django 读环境变量的时候把引号也当密码的一部分了，当然认证失败。

解决方案

去掉单引号：

env 复制代码

MAIN_DB_PASSWORD=TCA!@#2021

重启容器，数据库连接成功，页面终于能打开了。

第五场：Nginx 配置语法错误 ------ if 语句里不能用带 URI 的 proxy_pass

问题现象

页面能打开了，但访问文件服务器的 API 还是报错。检查 Nginx 日志，发现 Nginx 启动失败。

排查思路

看 Nginx 配置文件，有这么一段：

nginx 复制代码

if ($http_authorization) {
    proxy_pass http://file-nginx:8004/api/files/;
}

Nginx 的 if 语句里不能直接用带 URI 的 proxy_pass，这是语法错误。

解决方案

用 set 指令定义变量，避免直接在 if 中使用 URI：

nginx 复制代码

set $target "http://file-nginx:8004/api/files/";
if ($http_authorization) {
    proxy_pass $target;
}

或者干脆不用 if，用 location 匹配更清晰：

nginx 复制代码

location /api/files/ {
    proxy_pass http://file-nginx:8004/api/files/;
    proxy_set_header Authorization $http_authorization;
}

第六场：容器间 DNS 解析失败 ------ nginx 主机名找不到

问题现象

修好 Nginx 配置后，分析服务器还是报错：

复制代码

DNS resolution failed for hostname: nginx

分析服务器容器找不到 nginx 这个主机名。

排查思路

Docker 容器之间是通过 Docker 内部 DNS 解析主机名的。有时候 DNS 缓存有问题，或者容器网络没正确连接。

解决方案

重启分析服务器容器，刷新 DNS 缓存：

powershell 复制代码

docker restart codeanalysis-main-analysis-worker-1

重启后 DNS 解析正常，容器之间能互相通信了。

第七场：文件服务器 URL 格式错误 ------ bucket 名称不能少

问题现象

容器之间能通信了，但访问文件服务器还是报错：

复制代码

app只允许为数字和字母，且长度不允许超过40

排查思路

这个错误是文件服务器校验 bucket 名称时报的。看环境变量：

env 复制代码

FILE_SERVER_URL=http://nginx:8000/api/files/

URL 里没有 bucket 名称！文件服务器期望 URL 格式是 /api/files/{bucket}/。

解决方案

在 URL 里加上 bucket 名称 codedog：

env 复制代码

FILE_SERVER_URL=http://nginx:8000/api/files/codedog/

第八场：环境变量没更新 ------ 容器还在用旧配置

问题现象

改了环境变量，但容器里还是旧值。

排查思路

Docker 容器的环境变量是在容器创建时读入的，修改 .env.local 后，容器不会自动更新。

解决方案

停止并删除容器，用 docker-compose 重新创建：

powershell 复制代码

docker-compose down
docker-compose up -d

或者直接重建特定容器：

powershell 复制代码

docker rm -f codeanalysis-main-analysis-worker-1
docker-compose up -d analysis-worker

第二阶段：任务执行 ------ 文件服务器认证问题

经过上面八场硬仗，TCA 终于能启动了，页面能打开了，任务也能创建了。但运行任务时，又遇到了新的问题。

第九场：文件服务器 401 ------ Token 对不上号

问题现象

代码分析任务执行到一半，报：

复制代码

Fail to send result to file server! Error: HTTP Error 401: Unauthorized

页面上弹出"文件服务器异常"的提示。

排查思路

401 Unauthorized，认证失败。检查 Token 配置：

环境变量里：FILE_SERVER_TOKEN=657577ac0ef4c135a0d406b4433ce00b0fd28299
文件服务器数据库里：e91e0a1463f9a260f2b1efe756c2d0bfccbfb22a

两个 Token 完全不一样！

可能是初始化脚本创建了默认 Token，但我后来又配置了不同的 Token，两边没同步。

解决方案

更新数据库里的 Token：

sql 复制代码

DELETE FROM authtoken_token;
INSERT INTO authtoken_token (key, created, user_id) 
VALUES ('657577ac0ef4c135a0d406b4433ce00b0fd28299', NOW(), 1);

第十场：文件服务器 403 ------ 目录创建者为空

问题现象

Token 认证通过了，但上传文件报 403 Forbidden："无操作权限"。

排查思路

403 是权限问题。文件服务器里的目录是有权限控制的：

python 复制代码

from apps.file.models import AppUnit
unit = AppUnit.objects.get(name='codedog/public_server_temp')
print(unit.creator)  # '' 空字符串！

目录的创建者是空字符串，导致 codedog 用户没有写权限。

解决方案

python 复制代码

unit.creator = 'codedog'
unit.save()

第三阶段：数据入库 ------ 数据格式兼容问题

文件服务器的问题解决了，任务能执行了，但到了数据入库环节，又来了一连串的问题。

第十一场：result 数据藏在子对象里

问题现象

入库失败，报：

复制代码

KeyError: 'cloc_tuple_definition'

排查思路

下载工具返回的结果数据：

json 复制代码

{
  "result": {
    "files": {...},
    "cloc_tuple_definition": [...]
  }
}

数据都在 result 子对象里，不在顶层！代码直接从顶层读字段，当然找不到。

解决方案

修改 codecounthandler.py：

python 复制代码

def download_result_data(self):
    raw_data = download_and_load_json_file(self._task_result["result_data_url"])
    self._result_data = raw_data.get("result", raw_data)

第十二场：last_modifier 字段集体失踪

问题现象

刚修好 codecount，cpd 的入库又挂了：

复制代码

KeyError: 'last_modifier'

排查思路

cpd 工具返回的数据里，压根没有 last_modifier 字段。可能老版本有，新版本没了。

解决方案

把所有直接访问改成 .get() 加默认值，duphandler.py 里一共 6 处：

python 复制代码

owner=item.get("last_modifier", "")

第十三场：result_summary 字段也不全

问题现象

复制代码

KeyError: 'duplication_rate'

解决方案

python 复制代码

self._dup_scan.duplicate_rate = self._result_summary.get("duplication_rate", 0)
self._dup_scan.total_duplicate_line_count = self._result_summary.get("total_duplicate_line_count", 0)
self._dup_scan.total_line_count = self._result_summary.get("total_line_count", 0)

第十四场：lizard 工具返回的不是 zip

问题现象

复制代码

zipfile.BadZipFile: File is not a zip file

排查思路

cchandler.py 默认把结果文件当 zip 解压，但 lizard 返回的是 JSON，不是 zip！

下载 lizard 的结果数据看看：

json 复制代码

{
  "result": {
    "summary": {...},
    "detail": [
      {"path": "xxx.c", "issues": [...], ...}
    ]
  }
}

结构完全不一样！

解决方案

这是最大的一次改动，修改 cchandler.py 的多个方法：

download_result_data：先判断是否有 result 字段，有就是新格式，直接读 JSON；没有就是旧格式，解压 zip
read_cc_issue_data：新格式直接遍历 detail，旧格式从文件逐行读
字段访问全部加默认值

验证通过 ------ 终于跑通了

所有修复完成后，重新运行代码分析任务：

✅ codecount（代码统计）：入库成功
✅ cpd（重复代码检测）：入库成功
✅ lizard（圈复杂度检测）：入库成功

页面上也能正常看到分析结果了。

下面这几张分析结果历史截图把整个心酸过程体现的淋漓尽致，不过最终亮绿色标时的那种喜悦也是成就感满满^v：

下面这张图就是第一次成功分析的结果截图啦：

经验总结

折腾了这么多问题，总结几条经验：

1. 细心检查配置文件格式

BOM 字符、单引号包裹密码、YAML 语法错误，这些细节问题最容易忽略，但往往导致整个系统启动失败。

2. 环境变量改了要重启容器

Docker 容器不会自动读取新的环境变量，必须停止并删除容器，用 docker-compose 重新创建。

3. 日志是最好的老师

遇到问题别瞎猜，先看日志。docker logs 一看，错误堆栈明明白白。

4. 数据格式一定要确认

工具升级后，返回的字段可能增增减减。代码里最好都用 .get() 加默认值，别直接 dict["key"]。

5. 兼容新旧格式是个好习惯

不确定数据格式会不会变，就写兼容逻辑。raw_data.get("result", raw_data) 这种写法，既简单又安全。

改动文件清单

阶段	文件/配置	改动内容
部署	`docker-compose.yml`	去掉 BOM 字符
部署	`.env.local`	密码去掉单引号，URL 加上 bucket 名称
部署	`nginx.conf`	修复 if 语句语法错误
运行	数据库 `authtoken_token` 表	更新 Token
运行	数据库 `AppUnit` 表	设置目录创建者
入库	`codecounthandler.py`	兼容新旧数据格式
入库	`duphandler.py`	修复字段缺失问题
入库	`cchandler.py`	兼容 lizard 工具的 JSON 格式

写在最后

私有化部署开源项目，踩坑是难免的。这篇文章记录了从部署到运行到入库的十四个问题，希望能帮到同样在折腾 TCA 的你。

遇到问题别慌，一个一个解决，总能跑通的，也可以关注私信我wei(软趴趴的工程师)

腾讯TCA代码分析平台docker部署问题排查实战记录

TCA 代码分析平台私有化部署踩坑实录：从零到跑通的十四场硬仗

前言

第一阶段：部署启动 ------ 最基础的问题也是最烦人的

第一场：节点资源找不到 ------ 工具没地方跑

第二场：docker-compose.yml 有 BOM 字符 ------ 配置解析失败

第三场：页面空白 + 502 Bad Gateway ------ 容器没启动成功

第四场：数据库连接失败 ------ 密码格式坑人

第五场：Nginx 配置语法错误 ------ if 语句里不能用带 URI 的 proxy_pass

第六场：容器间 DNS 解析失败 ------ nginx 主机名找不到

第七场：文件服务器 URL 格式错误 ------ bucket 名称不能少

第八场：环境变量没更新 ------ 容器还在用旧配置

第二阶段：任务执行 ------ 文件服务器认证问题

第九场：文件服务器 401 ------ Token 对不上号

第十场：文件服务器 403 ------ 目录创建者为空

第三阶段：数据入库 ------ 数据格式兼容问题

第十一场：result 数据藏在子对象里

第十二场：last_modifier 字段集体失踪

第十三场：result_summary 字段也不全

第十四场：lizard 工具返回的不是 zip

验证通过 ------ 终于跑通了

经验总结

1. 细心检查配置文件格式

2. 环境变量改了要重启容器

3. 日志是最好的老师

4. 数据格式一定要确认

5. 兼容新旧格式是个好习惯

改动文件清单

写在最后