Docker中Django连接PostgreSQL遇UnicodeDecodeError求助

云上老周

2026-6-13

问题

尝试将Django应用连接至Docker容器中运行的PostgreSQL，执行python manage.py runserver或python manage.py makemigrations时出现以下错误：

System check identified 3 issues (0 silenced).
Exception in thread django-main-thread:
Traceback (most recent call last):
  File "C:\Users\Usuario\AppData\Local\Programs\Python\Python312\Lib\threading.py", line 1073, in _bootstrap_inner
    self.run()
  File "C:\Users\Usuario\AppData\Local\Programs\Python\Python312\Lib\threading.py", line 1010, in run
    self._target(*self._args, **self._kwargs)
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\utils\autoreload.py", line 64, in wrapper
    fn(*args, **kwargs)
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\core\management\commands\runserver.py", line 137, in inner_run
    self.check_migrations()
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\core\management\base.py", line 581, in check_migrations
    executor = MigrationExecutor(connections[DEFAULT_DB_ALIAS])
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\migrations\executor.py", line 18, in __init__
    self.loader = MigrationLoader(self.connection)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\migrations\loader.py", line 58, in __init__
    self.build_graph()
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\migrations\loader.py", line 235, in build_graph
    self.applied_migrations = recorder.applied_migrations()
                              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\migrations\recorder.py", line 89, in applied_migrations
    if self.has_table():
       ^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\migrations\recorder.py", line 63, in has_table
    with self.connection.cursor() as cursor:
         ^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\utils\asyncio.py", line 26, in inner
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\backends\base\base.py", line 320, in cursor
    return self._cursor()
           ^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\backends\base\base.py", line 296, in _cursor
    self.ensure_connection()
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\utils\asyncio.py", line 26, in inner
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\backends\base\base.py", line 279, in ensure_connection
    self.connect()
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\utils\asyncio.py", line 26, in inner
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\backends\base\base.py", line 256, in connect
    self.connection = self.get_new_connection(conn_params)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\utils\asyncio.py", line 26, in inner
    return func(*args, **kwargs)
           ^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\django\db\backends\postgresql\base.py", line 332, in get_new_connection
    connection = self.Database.connect(**conn_params)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "D:\Cositas\Python\Emergentes\env\Lib\site-packages\psycopg2\__init__.py", line 122, in connect
    conn = _connect(dsn, connection_factory=connection_factory, **kwasync)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xf3 in position 85: invalid continuation byte

已尝试的解决方法：

验证数据库使用UTF-8编码
删除并重新创建Docker中的UTF-8编码数据库
分别测试psycopg2和psycopg2-binary
检查配置中的特殊字符
删除并重新安装虚拟环境

疑问：

还能检查哪些内容来解决该错误？
是否可能是数据库中的数据导致此问题？
如何调试PostgreSQL中触发该错误的具体字节？

解决建议

一、额外检查项

强制PostgreSQL容器的编码初始化参数
启动Docker容器时，添加环境变量POSTGRES_INITDB_ARGS="--encoding=UTF8 --lc-collate=C --lc-ctype=C"，确保数据库初始化时严格使用UTF-8，避免容器内部系统编码与数据库编码不匹配。

显式配置Django数据库连接的字符集
在settings.py的数据库配置中添加client_encoding参数，强制客户端使用UTF-8连接：

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'your_db_name',
        'USER': 'your_user',
        'PASSWORD': 'your_password',
        'HOST': 'localhost',
        'PORT': '5432',
        'OPTIONS': {
            'client_encoding': 'UTF8',
        },
    }
}

检查Windows系统区域编码设置
打开控制面板→区域→管理→更改系统区域设置，勾选「Beta版：使用Unicode UTF-8提供全球语言支持」，重启系统后再尝试运行命令，避免系统默认编码干扰连接过程。

排查psycopg2生成的DSN字符串
在psycopg2/__init__.py的connect方法中临时添加调试代码，打印生成的DSN内容，查看是否包含非UTF-8字符：

def connect(dsn=None, connection_factory=None, cursor_factory=None, **kwargs):
    # 临时调试代码
    if dsn:
        print("DSN原始字节:", repr(dsn))
    # 原有逻辑...

二、是否由数据库数据导致？

从错误栈来看，错误发生在建立连接并检查迁移记录表的阶段，此时尚未读取业务数据，因此大概率不是数据库中已有数据导致的，问题核心应聚焦在连接过程的编码匹配上。若后续连接成功后操作数据时出现类似错误，再排查数据编码问题。

三、调试触发错误的具体字节

捕获并打印DSN原始字节
按上述方法修改psycopg2的connect方法，打印DSN的原始字节流，定位位置85的字节0xf3对应的具体内容，判断是哪个连接参数包含了非UTF-8字符。
开启PostgreSQL连接日志
修改Docker容器内的postgresql.conf，设置：
```
log_connections = on
log_line_prefix = '%t [%p]: [%c-%l] user=%u,db=%d,app=%a,client=%h '
```
重启容器后，通过docker logs <postgres_container_id>查看连接日志，分析客户端发送的编码相关参数，定位异常来源。

内容的提问来源于stack exchange，提问作者Gustavo Luis Serpa

Docker中Django连接PostgreSQL遇UnicodeDecodeError求助

问题 #

解决建议 #

一、额外检查项 #

二、是否由数据库数据导致？ #

三、调试触发错误的具体字节 #

问题

解决建议

一、额外检查项

二、是否由数据库数据导致？

三、调试触发错误的具体字节