v0.4.4

0.4.4

亮点

• 全面迁移 ESM：main 包声明 type: module，构建切换到 esbuild (via tsx build.ts)，产物为 ESM，修复 GramJS 子路径导入在 Node 22 下的加载问题。
• 网络栈精简：移除 axios/reconnecting-websocket，统一使用 Node 22 原生 fetch（undici）与自研 ReconnectingWebSocket，减少依赖并强化自动重连。
• NapCat 适配强化：WebSocket 支持重连，收消息时自动补齐媒体直链（get_file/get_record/get_image），语音/文件/图片可直接下载。
• 媒体处理更鲁棒：下载支持超时与本地路径兜底，NapCat 录音自动尝试 .amr.wav，失败时抛出明确错误。
• QQ 头像代理接口：新增 /qqAvatar/:userId 代理 QQ 头像并加缓存头，避免前端跨域/证书问题。
• CI/文档：优化路线图同步完成项；CI 拆分与修复（Prisma fake DATABASE_URL、canvas 依赖、重命名发布流程）。

详细变更

• ESM 构建链路
  • package.json 设为 type: module，tsconfig 改为 module: ESNext、moduleResolution: Bundler。
  • 构建脚本仅运行 tsx build.ts（移除重复 tsc），esbuild 输出 ESM 并注入 __dirname/__filename/require banner。
  • GramJS 相关导入统一追加 .js 后缀，避免 Node 22 的模块解析错误。
• 网络/依赖
  • 删除 axios、reconnecting-websocket；新增/升级 undici 用法、file-type@19、fast-xml-parser、fluent-ffmpeg。
  • ReconnectingWebSocket（零依赖）提供指数退避重连，NapCat 适配器直接使用。
  • fetchFile 等工具统一走 undici，允许自签证书（rejectUnauthorized: false）。
• NapCat 客户端
  • WebSocket 断线自动重连；上线/下线事件透传。
  • 收到媒体时调用 get_file/get_record/get_image 填充直链，语音兼容 mp3 转码返回。
  • 日志与错误处理更细，避免解析失败导致崩溃。
• 媒体转发
  • MediaFeature.downloadMedia 使用原生 fetch + AbortController；支持本地路径与 .amr → .wav 兜底。
  • 图片/视频/音频处理在文件不可读时回退到 URL 下载，错误信息更明确。
  • 单测改为 mock undici.fetch，覆盖异常分支。
• Telegram/GramJS
  • 所有 Telegram SDK 子路径改为显式 .js 导入，确保 ESM 解析；运行时不再出现 ERR_MODULE_NOT_FOUND。
• 接口与工具
  • 新增 GET /qqAvatar/:userId，转发 QQ 头像并加一天缓存。
  • URL 工具与头像/大脸获取统一用 undici，减少重复实现。
• CI/流程
  • CI 拆分：check/workflow 调整、fake DATABASE_URL 供 prisma generate，补齐 canvas 依赖；主发布流程重命名为 docker-publish.yml。
  • 优化路线图标记已完成项（启动 chown 移除、HTTP 客户端统一、WebSocket 重连、自研构建链路简化）。

兼容性与升级提示

• Node.js 需 >= 22（保持与 engines 一致）。若有自定义脚本/插件使用 CommonJS require，请按 ESM 规则或使用 createRequire。
• GramJS/Telegram 相关自定义导入需带 .js 后缀；第三方手写扩展如未更新可能报模块解析错误。
• NapCat WebSocket 如需关闭自动重连，可在创建参数中禁用 reconnect。

Full Changelog: v0.4.3...v0.4.4

v0.4.3

Q2TG v0.4.3 Release Notes

发布日期: 2025-12-02
版本: v0.4.3
重要性: 🔴 高优先级安全更新

---

📋 概述

v0.4.3 是一个重要的安全性和稳定性更新，实现了容器最小权限化，解决了 Prisma 迁移容错问题，并统一了日志格式。强烈建议所有用户升级。

---

🚀 主要更新

1. 容器最小权限化 🔒

改进内容：

• 容器现在以非 root 用户（node，UID 1000）运行
• 在构建阶段完成所有权限设置
• 移除运行时的 chown -R 和 chmod -R a+rwX 操作
• 提升安全性和启动速度

技术细节：

• 使用 node:22-slim 基础镜像自带的 node 用户（UID/GID 1000）
• 所有应用文件在构建时使用 --chown=node:node 设置所有权
• 数据目录在构建阶段创建并设置正确权限

2. Prisma 迁移容错机制 🛡️

改进内容：

• docker-entrypoint.sh 新增 P3005 错误自动处理
• 遇到"数据库非空"错误时自动 baseline 所有迁移
• 避免首次部署或数据库恢复时的启动失败

工作原理：

# 检测 P3005 错误
if grep -q "P3005" /tmp/migrate.log; then
  # 自动标记所有迁移为已应用
  for migration in ./prisma/migrations/*/; do
    prisma migrate resolve --applied "$migration_name"
  done
  # 重新运行迁移
  prisma migrate deploy
fi

---

⚠️ 重要：升级指南

🔴 必读：NapCat 权限配置

由于 q2tg 容器现在以 UID 1000 运行，必须确保 NapCat 也以相同的 UID 运行，否则会出现权限错误：

Error: EACCES: permission denied, open '/app/.config/QQ/.../file.amr'

解决方案（必须执行）：

步骤 1：配置 NapCat 运行用户

在 NapCat 的 compose.yaml 所在目录创建或编辑 .env 文件：

cd /path/to/napcat
cat > .env << 'EOF'
NAPCAT_UID=1000
NAPCAT_GID=1000
EOF

步骤 2：修复现有文件权限

# 将 NapCat 数据目录的所有文件改为 UID 1000
sudo chown -R 1000:1000 /path/to/napcat-data

步骤 3：重启 NapCat 容器

cd /path/to/napcat
docker compose down
docker compose up -d

步骤 4：验证配置

# 检查 NapCat 运行用户
docker exec napcat id napcat
# 应该输出: uid=1000(napcat) gid=1000(napcat) groups=1000(napcat)

# 检查 q2tg 运行用户
docker exec q2tg id
# 应该输出: uid=1000(node) gid=1000(node) groups=1000(node)

📦 Docker Compose 卷挂载

如果使用自定义的卷挂载路径，确保宿主机目录权限正确：

# 方法 1：修改宿主机目录权限
sudo chown -R 1000:1000 /path/to/data

# 方法 2：在 compose.yaml 中明确指定用户（可选）
services:
  q2tg:
    user: "1000:1000"  # 明确指定运行用户

🗄️ 数据库迁移

如果你的数据库已经存在表但没有迁移历史，新的容错机制会自动处理。首次启动时你会看到：

正在运行数据库迁移...
检测到 P3005 错误（数据库非空），尝试 baseline 所有迁移...
标记迁移为已应用: add_thread_id
重新运行迁移...
数据库迁移完成，启动应用...

---

🔧 其他改进

日志系统

• 从 log4js 完全迁移到 tslog
• 控制台按级别彩色输出
• 文件以 JSON 行格式按天分片
• 遵循 LOG_LEVEL 和 LOG_FILE_LEVEL 环境变量

文档

• 新增 docs/optimization-roadmap.md - 优化路线图
• 更新所有相关文档
• README 增补 CI/CD、版本、下载量等徽章

---

📊 性能提升

• 启动速度: 移除运行时递归 chown/chmod 操作，启动速度提升约 2-3 秒
• 安全性: 容器以非 root 用户运行，符合安全最佳实践
• 稳定性: 自动处理迁移错误，减少部署失败

---

🐛 已知问题

权限问题排查

如果升级后遇到权限错误，请按以下步骤排查：

1. 检查 NapCat 运行用户：

   docker exec napcat id napcat
   # 必须是 uid=1000

2. 检查文件权限：

   ls -l /path/to/napcat-data
   # 所有文件应该是 1000:1000

3. 检查环境变量：

   docker exec napcat env | grep NAPCAT
   # 应该显示 NAPCAT_UID=1000 和 NAPCAT_GID=1000

4. 查看日志：

   docker logs q2tg --tail 50 | grep -i "permission\|eacces"

---

📝 完整变更日志

v0.4.3 (2025-12-02)

✨ 新特性

• 容器最小权限化：使用 node 用户（UID 1000）运行
• Prisma 迁移自动容错机制
• 日志格式完全统一

🔧 改进

• 移除运行时权限操作，提升启动速度
• 优化 Dockerfile，移除重复的环境变量
• 简化 docker-entrypoint.sh

🐛 修复

• 修复 Prisma P3005 错误导致的启动失败
• 修复日志时间戳格式不一致问题
• 修复 GID 冲突问题（使用现有 node 用户）

📚 文档

• 新增优化路线图文档
• 更新升级指南
• 添加详细的权限配置说明

---

🔄 从 v0.4.2 升级

自动升级（推荐）

cd /path/to/q2tg_refactor
git pull
docker compose down
docker compose up -d --build

手动升级

1. 备份数据（可选但推荐）：

   docker exec postgres pg_dump -U user db_name > backup.sql

2. 配置 NapCat（必须）：

   cd /path/to/napcat
   echo "NAPCAT_UID=1000" > .env
   echo "NAPCAT_GID=1000" >> .env
   sudo chown -R 1000:1000 ./napcat-data
   docker compose down && docker compose up -d

3. 更新 q2tg：

   cd /path/to/q2tg_refactor
   git pull
   docker compose down
   docker compose up -d --build

4. 验证：

   docker logs q2tg --tail 30
   docker logs napcat --tail 30

---

💬 反馈与支持

如果遇到问题，请：

1. 查看本文档的"已知问题"部分
2. 检查 Docker 日志：docker logs q2tg 和 docker logs napcat
3. 在 GitHub Issues 中报告问题，并附上：
   • 错误日志
   • docker exec q2tg id 输出
   • docker exec napcat id napcat 输出
   • NapCat .env 文件内容

---

🙏 致谢

感谢所有测试和反馈的用户！

---

维护者: magisk317
项目地址: Q2TG

Full Changelog: v0.4.2...v0.4.3

v0.4.2

[v0.4.2] - 2025-12-02

✨ 改进

• 日志系统: 全面由 log4js 切换至 tslog，控制台按级别彩色输出，文件以 JSON 行格式按天分片（遵循 LOG_LEVEL/LOG_FILE_LEVEL）。
• 文档: 新增 docs/optimization-roadmap.md，汇总后续优化路线与技术栈更新建议。
• 可见性: README 增补 CI/CD、版本、下载量、GHCR、Star/Fork 等徽章，并添加 Star 趋势图。

⚠️ 升级提示

• 日志落盘路径仍以 LOG_FILE 为基名，但实际文件名带日期后缀（如 app.log.2025-12-01）；若有集中式采集/轮转脚本，请同步调整。

Full Changelog: v0.4.1...v0.4.2

v0.4.1

Q2TG v0.4.1 Release Note

本次更新主要集中在转发体验的细节优化、新增动态控制功能以及修复已知问题。

✨ 新特性 (Features)

• 动态控制命令 (/mode)
  • 新增 Telegram 管理员命令 /mode，支持实时调整配置无需重启。
  • /mode nickname <00|01|10|11>：控制昵称显示（第一位 QQ->TG，第二位 TG->QQ）。
  • /mode forward <00|01|10|11>：控制转发开关（第一位 QQ->TG，第二位 TG->QQ）。
• 环境变量增强
  • 新增 SHOW_NICKNAME_MODE：设置默认的昵称显示策略（默认 11）。
  • 新增 FORWARD_MODE：设置默认的转发开关策略（默认 11）。
• 配置模板
  • 新增 compose.example.yaml 作为标准配置参考。
  • compose.yaml 现已从版本控制中移除，避免更新时覆盖用户的本地配置。

🐛 问题修复 (Bug Fixes)

• QQ -> TG 转发
  • 修复昵称重复：修复了在启用 RichHeader（头像预览）时，图片/视频消息上方会重复显示文本昵称的问题。现在 RichHeader 模式下将自动隐藏文本昵称。
  • 修复话题归属：修复了部分消息（如媒体发送失败的回退消息）未正确发送到指定 Topic（话题），而是错误发送到 General（话题 ID 1）的问题。
• TG -> QQ 转发
  • 优化媒体发送：针对 NapCat 协议的限制，优化了语音和图片消息的转发策略。采用“文本头 + 媒体内容”的分离发送方式，确保昵称和内容均能正确显示，解决了合并转发中部分媒体类型无法查看的问题。

⚡️ 变更 (Changes)

• Git 策略调整：compose.yaml 被加入 .gitignore，请使用 compose.example.yaml 作为参考创建或更新您的配置文件。

升级指南

1. 拉取最新代码：git pull
2. 参考 compose.example.yaml 更新您的 compose.yaml，添加新的环境变量（可选）。
3. 重建并启动容器：docker compose up -d --build
   Full Changelog: v0.4.0...v0.4.1

v0.4.0

[v0.4.0] - 2024-12-01

🚀 重大重构

• 架构升级: 完成从 Controller 到 Feature 架构的迁移。
• 基础设施: 移除 OICQ 依赖，完全集成 node-napcat-ts。
• 消息系统: 实现 UnifiedMessage 统一消息系统和 MessageConverter 转换器。

✨ 新特性

• 合并转发: 支持 Telegram 到 QQ 的视频和文件合并转发。
• 拆分发送: 针对 Telegram 到 QQ 的图片和语音消息，采用拆分发送（昵称+媒体）策略，解决显示问题。
• GIF 优化: 自动识别 GIF 为视频类型，确保在 QQ 中正常播放动画。
• 跨容器传输: 实现共享目录传输策略，并提供 HTTP URL 回退机制，确保媒体传输稳定性。

🐛 修复

• 昵称显示: 修复转发消息中发送者昵称丢失的问题。
• 头像显示: 修复 Telegram 头像获取和显示问题。
• 类型安全: 修复大量 TypeScript 类型错误，优化类型定义。
• Docker: 优化 Dockerfile 和构建流程。

🗑️ 移除

• 移除所有 OICQ 相关代码和依赖。
• 移除 Windows 平台特定的路径处理逻辑。

Full Changelog: https://github.com/magisk317/Q2TG/commits/v0.4.0