v0.4.3

[magisk317]

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

---

This discussion was created from the release v0.4.3.