如果你也在折腾 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 标签注册成功后，工具就能找到执行环境了。
问题现象
启动容器时，环境变量怎么都不生效。明明在 .env.local 里配置了各种参数，容器里却读不到。
排查思路
环境变量不生效，可能是 docker-compose.yml 解析有问题。用编辑器打开一看，文件开头有个奇怪的符号 —— BOM 字符！
BOM（Byte Order Mark）是 UTF-8 编码的一个特殊标记，有些编辑器会自动加上，但 docker-compose 解析 YAML 时不认这个，导致整份配置文件解析失败。
解决方案
用 PowerShell 去掉 BOM 字符：
(Get-Content docker-compose.yml -Raw) -replace "^" | Set-Content docker-compose.yml -NoNewline
去掉 BOM 后，重新启动容器，环境变量终于生效了。
问题现象
访问 Web 页面，直接空白，浏览器还报 502 Bad Gateway。
排查思路
502 意味着 Nginx 代理失败了。检查一下后端容器状态：
docker ps
发现 main-server 容器根本没在运行！
找到真凶
查看容器日志：
docker logs codeanalysis-main-main-server-1
日志显示数据库连接失败，容器启动就挂了。
问题现象
main-server 容器启动失败，日志报：
Access denied for user 'root'@'mysql'
数据库密码认证失败。
排查思路
密码明明是对的，怎么会认证失败？仔细检查 .env.local 文件：
MAIN_DB_PASSWORD='TCA!@#2021'
好家伙，密码周围有单引号！Django 读环境变量的时候把引号也当密码的一部分了，当然认证失败。
解决方案
去掉单引号：
MAIN_DB_PASSWORD=TCA!@#2021
重启容器，数据库连接成功，页面终于能打开了。
问题现象
页面能打开了，但访问文件服务器的 API 还是报错。检查 Nginx 日志，发现 Nginx 启动失败。
排查思路
看 Nginx 配置文件，有这么一段：
if ($http_authorization) {
proxy_pass http://file-nginx:8004/api/files/;
}
Nginx 的 if 语句里不能直接用带 URI 的 proxy_pass，这是语法错误。
解决方案
用 set 指令定义变量，避免直接在 if 中使用 URI：
set $target "http://file-nginx:8004/api/files/";
if ($http_authorization) {
proxy_pass $target;
}
或者干脆不用 if，用 location 匹配更清晰：
location /api/files/ {
proxy_pass http://file-nginx:8004/api/files/;
proxy_set_header Authorization $http_authorization;
}
问题现象
修好 Nginx 配置后，分析服务器还是报错：
DNS resolution failed for hostname: nginx
分析服务器容器找不到 nginx 这个主机名。
排查思路
Docker 容器之间是通过 Docker 内部 DNS 解析主机名的。有时候 DNS 缓存有问题，或者容器网络没正确连接。
解决方案
重启分析服务器容器，刷新 DNS 缓存：
docker restart codeanalysis-main-analysis-worker-1
重启后 DNS 解析正常，容器之间能互相通信了。
问题现象
容器之间能通信了，但访问文件服务器还是报错：
app只允许为数字和字母，且长度不允许超过40
排查思路
这个错误是文件服务器校验 bucket 名称时报的。看环境变量：
FILE_SERVER_URL=http://nginx:8000/api/files/
URL 里没有 bucket 名称！文件服务器期望 URL 格式是 /api/files/{bucket}/。
解决方案
在 URL 里加上 bucket 名称 codedog：
FILE_SERVER_URL=http://nginx:8000/api/files/codedog/
问题现象
改了环境变量，但容器里还是旧值。
排查思路
Docker 容器的环境变量是在容器创建时读入的，修改 .env.local 后，容器不会自动更新。
解决方案
停止并删除容器，用 docker-compose 重新创建：
docker-compose down
docker-compose up -d
或者直接重建特定容器：
docker rm -f codeanalysis-main-analysis-worker-1
docker-compose up -d analysis-worker
经过上面八场硬仗，TCA 终于能启动了，页面能打开了，任务也能创建了。但运行任务时，又遇到了新的问题。
问题现象
代码分析任务执行到一半，报：
Fail to send result to file server! Error: HTTP Error 401: Unauthorized
页面上弹出"文件服务器异常"的提示。
排查思路
401 Unauthorized，认证失败。检查 Token 配置：
FILE_SERVER_TOKEN=657577ac0ef4c135a0d406b4433ce00b0fd28299e91e0a1463f9a260f2b1efe756c2d0bfccbfb22a两个 Token 完全不一样！
可能是初始化脚本创建了默认 Token，但我后来又配置了不同的 Token，两边没同步。
解决方案
更新数据库里的 Token：
DELETE FROM authtoken_token;
INSERT INTO authtoken_token (key, created, user_id)
VALUES ('657577ac0ef4c135a0d406b4433ce00b0fd28299', NOW(), 1);
问题现象
Token 认证通过了，但上传文件报 403 Forbidden："无操作权限"。
排查思路
403 是权限问题。文件服务器里的目录是有权限控制的：
from apps.file.models import AppUnit
unit = AppUnit.objects.get(name='codedog/public_server_temp')
print(unit.creator) # '' 空字符串！
目录的创建者是空字符串，导致 codedog 用户没有写权限。
解决方案
unit.creator = 'codedog'
unit.save()
文件服务器的问题解决了，任务能执行了，但到了数据入库环节，又来了一连串的问题。
问题现象
入库失败，报：
KeyError: 'cloc_tuple_definition'
排查思路
下载工具返回的结果数据：
{
"result": {
"files": {...},
"cloc_tuple_definition": [...]
}
}
数据都在 result 子对象里，不在顶层！代码直接从顶层读字段，当然找不到。
解决方案
修改 codecounthandler.py：
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)
问题现象
刚修好 codecount，cpd 的入库又挂了：
KeyError: 'last_modifier'
排查思路
cpd 工具返回的数据里，压根没有 last_modifier 字段。可能老版本有，新版本没了。
解决方案
把所有直接访问改成 .get() 加默认值，duphandler.py 里一共 6 处：
owner=item.get("last_modifier", "")
问题现象
KeyError: 'duplication_rate'
解决方案
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)
问题现象
zipfile.BadZipFile: File is not a zip file
排查思路
cchandler.py 默认把结果文件当 zip 解压，但 lizard 返回的是 JSON，不是 zip！
下载 lizard 的结果数据看看：
{
"result": {
"summary": {...},
"detail": [
{"path": "xxx.c", "issues": [...], ...}
]
}
}
结构完全不一样！
解决方案
这是最大的一次改动，修改 cchandler.py 的多个方法：
download_result_data：先判断是否有 result 字段，有就是新格式，直接读 JSON；没有就是旧格式，解压 zipread_cc_issue_data：新格式直接遍历 detail，旧格式从文件逐行读所有修复完成后，重新运行代码分析任务：
页面上也能正常看到分析结果了。
下面这几张分析结果历史截图把整个心酸过程体现的淋漓尽致，不过最终亮绿色标时的那种喜悦也是成就感满满v：
下面这张图就是第一次成功分析的结果截图啦：
折腾了这么多问题，总结几条经验：
BOM 字符、单引号包裹密码、YAML 语法错误，这些细节问题最容易忽略，但往往导致整个系统启动失败。
Docker 容器不会自动读取新的环境变量，必须停止并删除容器，用 docker-compose 重新创建。
遇到问题别瞎猜，先看日志。docker logs 一看，错误堆栈明明白白。
工具升级后，返回的字段可能增增减减。代码里最好都用 .get() 加默认值，别直接 dict["key"]。
不确定数据格式会不会变，就写兼容逻辑。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(软趴趴的工程师)
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。