143 lines
3.6 KiB
Markdown
143 lines
3.6 KiB
Markdown
## 🔒 彻底杜绝字符编码问题的方案
|
||
|
||
本文档说明如何在整个技术栈中确保使用 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 编码，彻底杜绝乱码问题。
|