Posted inリナックス

Linux ロケール・エンコーディング・タイムゾーン：UTF-8とマルチリージョンサーバー設定ガイド

Linux tutorial - IT technology blog
Linux tutorial - IT technology blog

新しくプロビジョニングされたサーバーにSSH接続し、非ASCII文字を含むファイル名を処理するスクリプトを実行すると、こんなエラーが出る：

UnicodeDecodeError: 'ascii' codec can't decode byte 0xe6 in position 0

あるいは、cronジョブが正確な時間に実行されているのに、ログのタイムスタンプがUTCで、チームが期待するのは東京時間だったりする。インシデント対応中にログ1行ごとに頭の中で時間計算をする羽目になる。これはエッジケースではない。すでにストレスを抱えた深夜2時に表面化し、ログはほとんど役に立たない状態になる。

Ubuntu 22.04サーバー（4GB RAM）で多言語コンテンツ処理パイプラインを動かしていたとき、この問題は早い段階で現実として現れた。プロビジョニング時からロケールとタイムゾーンを正しく設定するだけで、各実行時間が実際に短縮された。実行途中でエンコーディング例外が発生してバッチ全体を最初からやり直す、といったことがなくなったのだ。

なぜロケール・エンコーディング・タイムゾーンは絡み合っているのか

一見、無関係な3つの設定項目に見える。しかし実際は違う。

ロケールは、日付形式、数値のフォーマット、文字のソート順、そして最も重要な「使用する文字エンコーディング」といった言語固有の動作をOSにどう処理させるかを指示する。en_US.UTF-8のようなロケールには2つの部分がある：言語・地域コード（en_US）とエンコーディング（UTF-8）だ。多くのエンコーディングバグは、コードの問題ではなくロケールの未設定に起因している。

エンコーディングは、文字をバイトとしてどう保存するかを定義する。基本的なASCII以外のコンテンツを扱うサーバーにとって、UTF-8は唯一の合理的な選択肢だ。ASCIIと後方互換性があり、日本語、アラビア語、中国語、絵文字など、あらゆるUnicode文字をカバーする。

タイムゾーンはロケールとは別物だが、同様に重要だ。ログのタイムスタンプ、cronスケジュール、データベースレコード、スタック全体の時間関連すべてに影響を与える。

主要な環境変数のクイックリファレンス：

  • LANG — デフォルトロケール、すべてのLC_*変数のフォールバック
  • LC_ALL — すべてのLC_*変数を一括オーバーライド（使用は控えめに）
  • LC_CTYPE — 文字の分類とエンコーディング；UTF-8において最も重要
  • LC_TIME — 日付と時刻の形式
  • LC_MESSAGES — システムメッセージに使用される言語
  • LC_NUMERIC — 数値フォーマット（小数点区切り、千の位区切り）
  • TZ — 現在のシェルセッションのタイムゾーンオーバーライド

まず現在の設定を確認する

何かを変更する前に、現在の状態を確認しよう：

# すべてのロケール設定を確認
locale

# このシステムで利用可能なロケールを一覧表示
locale -a

# 現在のタイムゾーンとNTP同期状態を確認
timedatectl status

# またはタイムゾーンファイルを直接確認
cat /etc/timezone

新しくデプロイされた最小構成サーバーでは、localeの出力はよくこのようになっている：

LANG=
LC_CTYPE="POSIX"
LC_NUMERIC="POSIX"
LC_TIME="POSIX"
LC_ALL=

このPOSIXロケールは実質的にASCIIのみに対応している。非ASCIIバイトをこのシステムで処理しようとすると、後続の処理で問題が発生する。

UTF-8ロケールの設定

UbuntuとDebian

# ロケールデータをインストール（未インストールの場合）
sudo apt-get install -y locales

# 必要なロケールを生成
sudo locale-gen en_US.UTF-8 ja_JP.UTF-8

# デフォルトのシステムロケールを設定
sudo update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

# ログアウトせずに即座に適用
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

インタラクティブな方法が好みなら、これも使える：

sudo dpkg-reconfigure locales

テキストメニューで利用可能なロケールが一覧表示される。スペースキーで必要なものを選択し、次の画面でシステムデフォルトを設定する。ロケール文字列の正確な形式が分からない場合に便利だ。

RHEL、AlmaLinux、Rocky Linux

# 利用可能なロケールを一覧表示
localectl list-locales | grep en_US

# システムロケールを設定
sudo localectl set-locale LANG=en_US.UTF-8

# 確認
localectl status

システム全体に永続的に適用する

すべてのユーザーとシステムサービスを含むシステム全体に効果を持たせるには、/etc/locale.confを編集する：

sudo tee /etc/locale.conf << 'EOF'
LANG=en_US.UTF-8
LC_CTYPE=en_US.UTF-8
LC_MESSAGES=en_US.UTF-8
EOF

Debianベースのシステムでは、/etc/default/localeを確認する。LANG=en_US.UTF-8が含まれているはずだ。含まれていない場合、それがサービスがシェルで設定したロケールを無視する原因だ。

タイムゾーンの設定

timedatectlを使ったクリーンな方法

# タイムゾーンを検索
timedatectl list-timezones | grep -i tokyo
# Asia/Tokyo

timedatectl list-timezones | grep "America/New"
# America/New_York

# 設定する
sudo timedatectl set-timezone Asia/Tokyo

# 確認 — 再起動不要
timedatectl status

コンテナと最小環境向けの手動設定

timedatectlはsystemdを必要とするが、Dockerコンテナ内では利用できない。代わりにシンボリックリンクを使う方法を用いる：

# タイムゾーンファイルをリンク
sudo ln -sf /usr/share/zoneinfo/Asia/Tokyo /etc/localtime

# タイムゾーン名を書き込む
echo "Asia/Tokyo" | sudo tee /etc/timezone

# Debianベースのシステムでtzdataを再設定
sudo dpkg-reconfigure -f noninteractive tzdata

セッション単位・コマンド単位のタイムゾーン

# 現在のシェルのタイムゾーンをオーバーライド
export TZ="America/New_York"

# またはセッションを変更せずに単一コマンドのみオーバーライド
TZ="Europe/London" date

# タイムゾーンをまたいだcronの動作テストに便利
TZ="Asia/Tokyo" python3 -c "from datetime import datetime; print(datetime.now())"

実践：UTF-8が本当に重要な場面での対処法

クイックスモークテスト

# UTF-8ロケール設定済みであれば正しく表示されるはず
echo "日本語: 日本語テスト"
echo "中国語: 中文测试"
echo "韓国語: 한국어 테스트"

# PythonがUTF-8を認識しているか確認
python3 -c "import locale; print(locale.getpreferredencoding())"
# 「UTF-8」と表示されるはず

Pythonのエンコーディング処理

正しいシステムロケールが設定されていても、Pythonアプリが明示的な指定を必要とする場合がある。スクリプトが実行時に何を認識しているか確認しよう：

import sys
import locale

print(f"標準出力エンコーディング: {sys.stdout.encoding}")
print(f"ファイルシステムエンコーディング: {sys.getfilesystemencoding()}")
print(f"優先エンコーディング: {locale.getpreferredencoding()}")

これらのいずれかがasciiまたはANSI_X3.4-1968を返す場合、スクリプトを実行する前に以下を設定する：

PYTHONIOENCODING=utf-8 python3 your_script.py

systemdサービスはシェルのロケールを継承しない

これは予想外だった。ターミナルでは正常に動いているのに、Pythonスクリプトを実行するsystemdサービスがエンコーディングエラーを出し続けた。インタラクティブセッションも、Python REPLも、他のすべては正常に動作していた。問題は、systemdサービスがクリーンな環境で起動することにある。ログインシェルのロケール設定を継承しないのだ。

ユニットファイルで明示的に環境変数を宣言することで解決する：

# /etc/systemd/system/myapp.service
[Service]
Environment="LANG=en_US.UTF-8"
Environment="LC_ALL=en_US.UTF-8"
Environment="PYTHONIOENCODING=utf-8"
ExecStart=/usr/bin/python3 /opt/myapp/app.py
sudo systemctl daemon-reload
sudo systemctl restart myapp

cronジョブとタイムゾーン

cronによる/etc/localtimeの処理はディストリビューションによって一貫性がない。Debianベースのシステムは通常正しく認識するが、RHELや最小構成コンテナイメージはそうでない場合が多い。確実にするために、crontabの先頭でタイムゾーンを宣言しよう：

crontab -e
# crontabファイルの先頭に追加
TZ=Asia/Tokyo

# UTCではなく東京時間の午前9:00に実行される
0 9 * * * /opt/scripts/daily_report.sh

完全な確認スクリプト

#!/bin/bash
echo "=== ロケール ==="
locale

echo ""
echo "=== タイムゾーン ==="
timedatectl status 2>/dev/null | grep -E "Time zone|Local time" || date

echo ""
echo "=== Pythonエンコーディング ==="
python3 -c "
import locale, sys
print(f'  ロケール: {locale.getlocale()}')
print(f'  エンコーディング: {locale.getpreferredencoding()}')
print(f'  標準出力: {sys.stdout.encoding}')
"

echo ""
echo "=== UTF-8書き込み・読み取りテスト ==="
echo "テスト 测试 한국어" > /tmp/utf8_test.txt
cat /tmp/utf8_test.txt
file /tmp/utf8_test.txt

よくある落とし穴

  • SSHログイン後にロケールが適用されない：/etc/environmentを確認する。シェルプロファイルではなくPAM経由でこのファイルを読み込むシステムがある。他の方法が効かない場合はここにLANG=en_US.UTF-8を追加する。
  • DockerコンテナがPOSIXに戻る：ENV LANG=en_US.UTF-8とENV LC_ALL=en_US.UTF-8をDockerfileに追加する。ベースイメージはこれらを設定してくれない。
  • OSのタイムゾーンが正しいのにMySQL/PostgreSQLのタイムスタンプがおかしい：データベースのタイムゾーンは別途設定が必要だ。MySQLの場合はmy.cnfにdefault-time-zone='+09:00'を、PostgreSQLの場合はpostgresql.confにtimezone = 'Asia/Tokyo'を設定する。
  • LC_ALLとLANG：LC_ALLを設定するのは荒っぽい方法だ。個別のLC_*設定をすべて上書きしてしまう。本番サーバーではLANGと実際に必要な特定のLC_*値のみを設定する。より細かい制御ができ、影響範囲も小さくなる。

新規サーバーのチェックリスト

プロビジョニングする新規サーバーには、他の何かをインストールする前にこの手順を実行している：

# 1. ロケールを生成して設定
sudo locale-gen en_US.UTF-8
sudo update-locale LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8

# 2. タイムゾーンを設定
sudo timedatectl set-timezone Asia/Tokyo

# 3. NTPが有効であることを確認（時刻が正確に保たれるため）
timedatectl | grep NTP

# 4. シェル環境を再読み込み
source /etc/default/locale 2>/dev/null || source /etc/locale.conf

# 5. 最終確認
locale && date

プロビジョニング時に、何かをインストールする前にロケールとタイムゾーンを正しく設定する。これにより、本番環境で正体不明のエンコーディングバグを追いかける羽目にはならない。最初からこれを固定した後、ログファイルで見ていたエンコーディングエラーは完全に消えた。セットアップ時の2つのコマンドで、後のデバッグ時間を何時間も節約できる。

マルチリージョンチームには：サーバーが動作するタイムゾーンを文書化し、一貫性を保つこと。インフラログにはUTCを使うのが堅実な慣例だ。アプリケーション層で変換すれば、チームメンバーが複数の国にまたがっていても曖昧さがなくなる。何を選んでも、それを明示的にしてプロビジョニングスクリプトに記述する。タイムゾーンは忘れやすく、後から修正するのは非常に面倒だ。

Share:
Tags: