MTranServer故障排查手册：常见问题与解决方案
MTranServer故障排查手册：常见问题与解决方案
【免费下载链接】MTranServer Low-resource, fast, and privately self-host free version of Google Translate - 低占用速度快可私有部署的自由版 Google 翻译 
项目地址: https://gitcode.com/gh_mirrors/mt/MTranServer
MTranServer作为一款低占用、速度快且可私有部署的自由版Google翻译工具，在使用过程中可能会遇到各种问题。本手册将帮助您快速定位并解决MTranServer的常见故障，确保翻译服务稳定运行。
服务器启动故障排查
端口占用问题
症状：启动时报错"Address already in use"或"端口已被占用"
解决方案：
- 检查当前端口占用情况：
netstat -tuln | grep 8989 - 更改默认端口（8989）为其他可用端口：
export MT_PORT=9000 ./mtranserver - 或终止占用端口的进程后重启服务
依赖缺失问题
症状：启动时提示缺少特定库或模块
解决方案：
- 确保已安装所有依赖：
# 使用npm npm install # 或使用bun bun install - 检查是否有缺失的系统库，根据错误提示安装相应依赖包
配置文件错误
症状：启动失败并显示配置相关错误信息
解决方案：
- 检查配置文件格式是否正确，确保JSON语法无误
- 验证配置文件路径是否正确，默认配置目录为
~/.config/mtran/server - 尝试删除配置文件，让系统生成默认配置文件后重新启动
翻译功能故障排查
翻译无响应
症状：提交翻译请求后长时间无响应或返回超时
解决方案：
- 检查服务健康状态：访问
http://localhost:8989/health确认服务是否正常运行 - 查看日志文件，设置日志级别为debug获取详细信息：
export MT_LOG_LEVEL=debug ./mtranserver - 检查网络连接，确保服务器可以访问必要的外部资源（如翻译API）
翻译结果不正确或乱码
症状：翻译结果与预期不符或出现乱码
解决方案：
- 检查源语言和目标语言设置是否正确
- 确认输入文本编码是否为UTF-8
- 尝试更新语言模型：
# 确保离线模式已关闭 export MT_OFFLINE=false ./mtranserver - 检查是否使用了最新版本的MTranServer，考虑更新到最新版
MTranServer的Web翻译界面，可在此检查语言设置和翻译结果
API访问问题
认证失败
症状：调用API时返回"Unauthorized"或"认证失败"
解决方案：
- 检查API token是否正确设置：
export MT_API_TOKEN="your_token_here" ./mtranserver - 确保请求中包含正确的认证信息，可通过两种方式：
- Header:
Authorization: Bearer - Query:
?token=
- Header:
- 检查API访问权限设置，确认是否限制了特定IP或域名
API文档无法访问
症状：无法访问Swagger API文档页面
解决方案：
- 确认Web UI已启用：
export MT_ENABLE_UI=true ./mtranserver - 访问API文档地址：
http://localhost:8989/docs
MTranServer的Swagger API文档界面，可在此测试API功能
性能问题
翻译速度慢
症状：翻译响应时间过长
解决方案：
- 检查系统资源使用情况，确保CPU和内存充足
- 调整工作进程空闲超时设置：
export MT_WORKER_IDLE_TIMEOUT=600 ./mtranserver - 启用离线模式减少网络请求：
export MT_OFFLINE=true ./mtranserver
内存占用过高
症状：服务器内存占用持续增加
解决方案：
- 监控内存使用情况，确定是否有内存泄漏
- 尝试降低工作进程数量
- 清理缓存：
# 具体命令取决于缓存实现方式
高级故障排查
查看日志文件
日志文件通常位于配置目录下的logs文件夹中，或通过控制台输出。设置适当的日志级别可以帮助诊断问题：
# 设置日志级别为debug
export MT_LOG_LEVEL=debug
# 设置日志级别为info
export MT_LOG_LEVEL=info
# 设置日志级别为warn
export MT_LOG_LEVEL=warn
# 设置日志级别为error
export MT_LOG_LEVEL=error
使用健康检查端点
MTranServer提供多个健康检查端点，可用于监控服务状态：
/health- 基本健康检查/__heartbeat__- 心跳检查/__lbheartbeat__- 负载均衡器心跳检查
重新安装MTranServer
如果以上方法都无法解决问题，可以尝试重新安装：
# 克隆仓库
git clone https://gitcode.com/gh_mirrors/mt/MTranServer
cd MTranServer
# 安装依赖
npm install
# 构建项目
npm run build
# 启动服务
npm start
常见问题解答
Q: MTranServer支持哪些语言？
A: 可通过访问/languages端点获取支持的语言列表，或查看官方文档了解详细信息。
Q: 如何更新语言模型？
A: 确保MT_OFFLINE设置为false，服务器会自动下载和更新语言模型。
Q: 能否在没有网络的环境下使用MTranServer？
A: 可以，设置export MT_OFFLINE=true启用离线模式，但需要先下载所需的语言模型。
MTranServer翻译效果示例，展示多语言翻译能力
通过以上方法，大多数MTranServer的常见问题都可以得到解决。如果问题仍然存在，请查看项目的issue跟踪系统或社区论坛获取更多帮助。
【免费下载链接】MTranServer Low-resource, fast, and privately self-host free version of Google Translate - 低占用速度快可私有部署的自由版 Google 翻译 项目地址: https://gitcode.com/gh_mirrors/mt/MTranServer
