From 63d4011796b360c20190276992a857ed38704600 Mon Sep 17 00:00:00 2001
From: yml <yml@yml.com>
Date: Fri, 5 Jun 2026 21:27:26 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0mysql=E9=BB=98=E8=AE=A4?=
 =?UTF-8?q?=E7=BC=96=E7=A0=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 deploy/docker-compose.prod.yml |   2 +
 deploy/mysql/my.cnf            |  11 +++
 docs/charset-best-practices.md | 142 +++++++++++++++++++++++++++++++++
 frontend/tsconfig.json         |   3 +-
 4 files changed, 157 insertions(+), 1 deletion(-)
 create mode 100644 deploy/mysql/my.cnf
 create mode 100644 docs/charset-best-practices.md

diff --git a/deploy/docker-compose.prod.yml b/deploy/docker-compose.prod.yml
index 9c4e2ad..3c95992 100644
--- a/deploy/docker-compose.prod.yml
+++ b/deploy/docker-compose.prod.yml
@@ -2,12 +2,14 @@ services:
   mysql:
     image: mysql:8.4
     restart: unless-stopped
+    command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
     env_file:
       - ../backend/.env
     environment:
       TZ: Asia/Shanghai
     volumes:
       - mysql_data:/var/lib/mysql
+      - ./mysql/my.cnf:/etc/mysql/conf.d/my.cnf:ro
     deploy:
       resources:
         limits:
diff --git a/deploy/mysql/my.cnf b/deploy/mysql/my.cnf
new file mode 100644
index 0000000..4f76b4f
--- /dev/null
+++ b/deploy/mysql/my.cnf
@@ -0,0 +1,11 @@
+[client]
+default-character-set = utf8mb4
+
+[mysql]
+default-character-set = utf8mb4
+
+[mysqld]
+character-set-server = utf8mb4
+collation-server = utf8mb4_unicode_ci
+init-connect = 'SET NAMES utf8mb4'
+skip-character-set-client-handshake
diff --git a/docs/charset-best-practices.md b/docs/charset-best-practices.md
new file mode 100644
index 0000000..88bcebc
--- /dev/null
+++ b/docs/charset-best-practices.md
@@ -0,0 +1,142 @@
+## 🔒 彻底杜绝字符编码问题的方案
+
+本文档说明如何在整个技术栈中确保使用 UTF-8 编码，避免出现乱码问题。
+
+### 1. MySQL 服务器配置（已完成 ✅）
+
+**配置文件：** `deploy/mysql/my.cnf`
+
+```ini
+[client]
+default-character-set = utf8mb4
+
+[mysql]
+default-character-set = utf8mb4
+
+[mysqld]
+character-set-server = utf8mb4
+collation-server = utf8mb4_unicode_ci
+init-connect = 'SET NAMES utf8mb4'
+skip-character-set-client-handshake
+```
+
+**Docker Compose 配置：** `deploy/docker-compose.prod.yml`
+
+```yaml
+mysql:
+  command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
+  volumes:
+    - ./mysql/my.cnf:/etc/mysql/conf.d/my.cnf:ro
+```
+
+### 2. 数据库连接字符集（已完成 ✅）
+
+**配置：** `backend/internal/config/config.go`
+
+```go
+MySQLDSN: "hfb:secret@tcp(127.0.0.1:3306)/hfb_sys?charset=utf8mb4&parseTime=True&loc=Local"
+```
+
+**关键参数：**
+- `charset=utf8mb4` - 强制使用 UTF-8 编码
+- `parseTime=True` - 正确解析时间类型
+- `loc=Local` - 使用本地时区
+
+### 3. 数据库表结构（已完成 ✅）
+
+**迁移文件：** `backend/migrations/*.sql`
+
+```sql
+CREATE TABLE table_name (
+  ...
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+**转换现有表：**
+```sql
+ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+### 4. 后端 API 响应头（建议添加）
+
+**在 HTTP 响应中设置：**
+```go
+w.Header().Set("Content-Type", "application/json; charset=utf-8")
+```
+
+### 5. 前端 HTML 元信息（已完成 ✅）
+
+**index.html：**
+```html
+<meta charset="UTF-8">
+```
+
+### 6. 文件编辑器配置
+
+**确保所有代码文件使用 UTF-8：**
+- `.editorconfig` - 统一团队编码
+- IDE 设置 - 文件编码为 UTF-8
+- Git 设置 - 避免行尾符问题
+
+### 7. 验证检查清单
+
+部署后执行以下命令验证：
+
+```bash
+# 1. 检查 MySQL 字符集配置
+docker exec -i deploy-mysql-1 mysql -u hfb -p<password> -e "SHOW VARIABLES LIKE 'character%';"
+
+# 2. 检查表字符集
+docker exec -i deploy-mysql-1 mysql -u hfb -p<password> hfb_sys -e "SHOW CREATE TABLE announcements\G"
+
+# 3. 验证数据正确性
+docker exec -i deploy-mysql-1 mysql -u hfb -p<password> hfb_sys -e "SELECT id, title FROM announcements LIMIT 3;"
+```
+
+### 8. 常见问题排查
+
+**问题：数据库中已有乱码数据**
+```bash
+# 执行修复脚本
+docker exec -i deploy-mysql-1 mysql -u hfb -p<password> hfb_sys < backend/migrations/000008_fix_announcement_charset.sql
+```
+
+**问题：新插入的数据仍然乱码**
+- 检查数据库连接 DSN 是否包含 `charset=utf8mb4`
+- 检查 MySQL 配置文件是否生效
+- 重启 MySQL 容器使配置生效
+
+**问题：只有某些字段乱码**
+```sql
+-- 转换特定列
+ALTER TABLE table_name MODIFY column_name VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+### 9. 部署流程
+
+每次部署时确保：
+
+1. ✅ MySQL 配置文件已挂载
+2. ✅ 环境变量 MYSQL_DSN 包含 charset 参数
+3. ✅ 新建表使用正确的字符集
+4. ✅ 迁移脚本指定字符集
+
+### 10. 开发规范
+
+**新建表时必须指定：**
+```sql
+CREATE TABLE new_table (
+  ...
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='表注释';
+```
+
+**修改表时保持一致：**
+```sql
+ALTER TABLE existing_table CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
+```
+
+---
+
+## 总结
+
+通过以上配置，确保了从数据库服务器 → 连接驱动 → 表结构 → 应用层 → 前端展示的完整链路都使用 UTF-8 编码，彻底杜绝乱码问题。
diff --git a/frontend/tsconfig.json b/frontend/tsconfig.json
index 28c21b6..8c2ffe4 100644
--- a/frontend/tsconfig.json
+++ b/frontend/tsconfig.json
@@ -7,5 +7,6 @@
       "@/*": ["./src/*"]
     }
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"]
+  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue"],
+  "exclude": ["src/**/__tests__/**", "src/**/*.spec.ts", "src/**/*.test.ts", "node_modules"]
 }