issue98: 資格情報 (DB/AMQP) の取り扱いを改善する

.gitignore

@@ -1,4 +1,8 @@
 *.old
 docker-compose.custom*.yml
 /docker-compose*.yml
+# init-env.sh などで生成される .env はパスワードを含むため Git 管理対象外
+# (init-env.sh --force 時に作られるバックアップ .env.bak.<timestamp> も対象)
+**/.env
+**/.env.bak.*
 

Environment.md

@@ -4,13 +4,17 @@
 以下では各構成で共通的な環境変数について示します。
 各構成で独自の環境変数が定義されている場合もありますので、それぞれの説明を参照してください。
 
+> **デフォルト値の位置付け**: 以下の表に示す `DATABASE_URL` / `AMQP_URL` / `CACHE_URL` 等のデフォルト値は **kompira コンテナイメージ自体の既定値** であり、docker compose を経由せずコンテナを直接動かす場合などに参照されるものです。**ke2-docker の compose ファイルでは別途上書きされており**、内部 `postgres` / `rabbitmq` / `redis` コンテナへの接続情報 (`DATABASE_USER` / `DATABASE_PASSWORD` / `DATABASE_NAME` / `AMQP_USER` / `AMQP_PASSWORD` から組み立てた URL、または利用者が指定した `DATABASE_URL` / `AMQP_URL`) が実際の接続先として使われます。
+
 | 環境変数名            | デフォルト                                          | 意味                       |
 |-----------------------|-----------------------------------------------------|----------------------------|
 | `HOSTNAME`            | (下記参照)                                          | ホスト名                   |
 | `KOMPIRA_IMAGE_NAME`  | "kompira.azurecr.io/kompira-enterprise"             | Kompira イメージ           |
 | `KOMPIRA_IMAGE_TAG`   | (下記参照)                                          | Kompira タグ               |
 | `DATABASE_URL`        | "pgsql://kompira@//var/run/postgresql/kompira"      | データベースの接続先       |
+| `DATABASE_USER` / `DATABASE_PASSWORD` / `DATABASE_NAME` | (下記参照)                | DATABASE_URL の組み立て要素 |
 | `AMQP_URL`            | "amqp://guest:guest@localhost:5672"                 | メッセージキューの接続先   |
+| `AMQP_USER` / `AMQP_PASSWORD` | (下記参照)                                  | AMQP_URL の組み立て要素     |
 | `CACHE_URL`           | "redis://localhost:6379"                            | キャッシュの接続先         |
 | `TZ`                  | "Asia/Tokyo"                                        | タイムゾーン               |
 | `LANGUAGE_CODE`       | "ja"                                                | 言語設定                   |
@@ -43,6 +47,56 @@ Kompira に必要なサブシステムである、データベースやメッセ
 
 参考: https://django-environ.readthedocs.io/en/latest/types.html#environ-env-db-url
 
+なお ke2-docker の compose ファイルでは、`DATABASE_URL` / `AMQP_URL` を直接指定しなかった場合、後述の `DATABASE_USER` 等の個別変数から URL を自動構築する仕組みになっています。
+
+## DATABASE_USER / DATABASE_PASSWORD / DATABASE_NAME / AMQP_USER / AMQP_PASSWORD
+
+接続情報を URL 文字列として `DATABASE_URL` / `AMQP_URL` で指定する代わりに、ユーザ名・パスワード・データベース名を個別の環境変数で指定できます。
+
+| 環境変数名            | デフォルト  | 用途                                                                    |
+|-----------------------|-------------|-------------------------------------------------------------------------|
+| `DATABASE_USER`       | "kompira"   | DATABASE_URL のユーザ名。single/basic では postgres コンテナの初期ユーザ名にも適用 |
+| `DATABASE_PASSWORD`   | "kompira"   | DATABASE_URL のパスワード。single/basic では postgres コンテナの初期パスワードにも適用 |
+| `DATABASE_NAME`       | "kompira"   | DATABASE_URL のデータベース名。single/basic では postgres コンテナの初期 DB 名にも適用 |
+| `AMQP_USER`           | "guest"     | AMQP_URL のユーザ名。rabbitmq コンテナの初期ユーザ名にも適用            |
+| `AMQP_PASSWORD`       | "guest"     | AMQP_URL のパスワード。rabbitmq コンテナの初期パスワードにも適用        |
+
+これらのデフォルト値は互換性のための仮の値です。本番運用前に必ず変更してください。
+
+> **コンテナ初期化への適用は初回起動時のみ**: `DATABASE_USER` / `DATABASE_PASSWORD` / `DATABASE_NAME` の postgres コンテナへの適用 (`POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB`)、および `AMQP_USER` / `AMQP_PASSWORD` の rabbitmq コンテナへの適用 (`RABBITMQ_DEFAULT_USER` / `RABBITMQ_DEFAULT_PASS`) は、それぞれデータボリュームが空の **初回起動時のみ** 行われます。既存のデータボリュームを残したまま値を変更しても、DB 内のユーザ・パスワード・データベース名は更新されません。後から変更する手順は管理者マニュアル「資格情報管理」章を参照してください。
+
+`DATABASE_URL` または `AMQP_URL` を直接指定した場合、**アプリケーション側 (kompira / kengine / jobmngrd) の接続先** には指定された URL がそのまま使われ、対応する個別変数 (`DATABASE_USER` 等または `AMQP_USER` 等) は **接続先 URL の組み立てには使われなくなります**。一方、single/basic 構成における **postgres / rabbitmq コンテナの初期化** には個別変数の値が引き続き使われます (上記「コンテナ初期化への適用は初回起動時のみ」参照)。アプリ側と内部コンテナ側で別の値になると認証不整合が起きるため、`DATABASE_URL` / `AMQP_URL` を独自に指定する場合は個別変数も対応する値に揃えるか、または `DATABASE_URL` / `AMQP_URL` 側を内部コンテナの初期値と一致させてください。
+
+### URL 安全でない文字を含む資格情報の扱い
+
+`DATABASE_USER` / `DATABASE_PASSWORD` / `DATABASE_NAME` および `AMQP_USER` / `AMQP_PASSWORD` のいずれかに URL 安全でない文字 (RFC 3986 unreserved set 以外。`@` `:` `/` `%` 等の予約文字や空白などを含む) を含む値を設定する場合、組み立てられた URL に正しく埋め込めない問題が発生します。本節はパスワードに限らず、ユーザ名・DB 名にも適用されます (`DATABASE_URL` / `AMQP_URL` を直接指定する場合は、利用者があらかじめパーセントエンコードして埋め込む必要があります)。
+
+URL に文字列を埋め込む際のエンコード規約は [RFC 3986 (URI: Generic Syntax)](https://datatracker.ietf.org/doc/html/rfc3986) で定められています。`DATABASE_URL` / `AMQP_URL` の userinfo (ユーザ名・パスワード部分) や path (DB 名部分) で **URL の区切り文字として解釈される文字** (主に `@` `:` `/` `?` `#` `%` や空白等) を **データの一部として** 埋め込む場合は、`%XX` (XX は ASCII コードの 16 進数表記) でパーセントエンコードする必要があります。安全側に倒すなら、RFC 3986 §2.3 で「unreserved」と定義された英数字および `-` `_` `.` `~` 以外の文字をすべてエンコードしておけば確実です。許容される文字とエンコード規則の詳細は [RFC 3986 §3.2.1 (userinfo)](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) / [§3.3 (path)](https://datatracker.ietf.org/doc/html/rfc3986#section-3.3) を参照してください。
+
+主要な変換例:
+
+| 文字 | エンコード後 | 文字       | エンコード後 |
+|------|--------------|------------|--------------|
+| `@`  | `%40`        | `?`        | `%3F`        |
+| `:`  | `%3A`        | `#`        | `%23`        |
+| `/`  | `%2F`        | `%`        | `%25`        |
+| `+`  | `%2B`        | `&`        | `%26`        |
+| `=`  | `%3D`        | ` ` (空白) | `%20`        |
+
+実例: 実パスワード `p@ss:w0rd` を `DATABASE_URL` に埋め込む場合は、`pgsql://user:p%40ss%3Aw0rd@host:5432/db` のように `p@ss:w0rd` → `p%40ss%3Aw0rd` に変換して指定します。
+
+各環境変数の挙動:
+
+- **`DATABASE_USER` / `DATABASE_PASSWORD` / `DATABASE_NAME`**:
+    - `DATABASE_URL` を直接指定するか、`scripts/init-env.sh` で `.env` を生成する場合は、URL 安全でない文字を含む値も利用可能です (受け取り側の django-environ が URL デコードするため、kompira コンテナイメージのバージョン依存もありません)。
+    - 一方、これらの個別変数を指定して compose 側に `DATABASE_URL` を組み立てさせる場合は、いずれも URL に未エンコードのまま埋め込まれるため、RFC 3986 unreserved set (英数字と `-_.~`) のみを使用してください。
+- **`AMQP_USER` / `AMQP_PASSWORD`**: kompira コンテナイメージが **v2.0.5.post2 以降** である必要があります (AMQP_URL の userinfo を URL デコードする修正が必要なため)。v2.0.5.post1 以前のイメージを利用する場合、`AMQP_USER` / `AMQP_PASSWORD` には RFC 3986 unreserved set (英数字と `-_.~`) のみを使用してください。
+    - また DB 系同様、これらの個別変数を指定して compose 側に `AMQP_URL` を組み立てさせる場合も、URL に未エンコードのまま埋め込まれるため、unreserved set のみを使用してください (`scripts/init-env.sh` 経由なら自動でエンコードされます)。
+
+URL 安全でない文字を含むユーザ名・パスワード・DB 名を安全に設定するには、`scripts/url-encode.sh` で個別の文字列をエンコードするか、`scripts/init-env.sh` で `.env` を自動生成する方法を推奨します (init-env.sh は内部で url-encode.sh を利用して URL エンコードを自動処理します)。詳細は管理者マニュアル「資格情報管理」章を参照してください。
+
+また、シェルコマンドで値全体をシングルクオートで囲む形式 (`DATABASE_URL='pgsql://...'` / `AMQP_URL='amqps://...'` 等) を使う場合、シェル特殊文字 (`#` / 空白 / `$` / `!` 等) を含む値でも安全にコピペできますが、値自体に `'` (シングルクオート) を含む場合は閉じてしまうため別途エスケープが必要です (`'\''` での逐次切替、または `scripts/init-env.sh` で `.env` を生成して利用する等)。詳細な対処方法は管理者マニュアル「資格情報管理」§5 を参照してください。
+
 ## TZ / LANGUAGE_CODE
 
 各コンテナのタイムゾーンと言語コードを設定します。

ke2/cluster/swarm/docker-compose.override.yml

@@ -16,6 +16,12 @@ x-multi-replicated:
   placement:
     max_replicas_per_node: 1
 
+# Swarm 構成では postgres コンテナを起動せず外部 DB を前提とするため、DATABASE_URL の指定を必須とする。
+# setup_stack.sh は DATABASE_URL を事前に export してから docker compose config を呼ぶため、
+# スクリプト経由のセットアップでは発火しない。スクリプト未経由のセットアップで未指定の場合に即エラーで停止する。
+x-required-db-env: &required-db-env
+  DATABASE_URL: '${DATABASE_URL:?DATABASE_URL must be set: e.g., pgsql://user:password@host:5432/dbname}'
+
 services:
   redis:
     hostname: "re-{{.Node.Hostname}}"
@@ -37,19 +43,22 @@ services:
   jobmngrd:
     hostname: "jm-{{.Node.Hostname}}"
     environment:
-      - AMQP_URL=${AMQP_URL:-amqp://guest:guest@mq-<<.Node.Hostname>>:5672}
+      <<: *required-db-env
+      AMQP_URL: ${AMQP_URL:-amqp://${AMQP_USER:-guest}:${AMQP_PASSWORD:-guest}@mq-<<.Node.Hostname>>:5672}
     logging: *default-logging
     deploy: *multi-replicated
   kengine:
     hostname: "ke-{{.Node.Hostname}}"
     environment:
-      - AMQP_URL=${AMQP_URL:-amqp://guest:guest@mq-<<.Node.Hostname>>:5672}
+      <<: *required-db-env
+      AMQP_URL: ${AMQP_URL:-amqp://${AMQP_USER:-guest}:${AMQP_PASSWORD:-guest}@mq-<<.Node.Hostname>>:5672}
     logging: *default-logging
     deploy: *multi-replicated
   kompira:
     hostname: "ap-{{.Node.Hostname}}"
     environment:
-      - AMQP_URL=${AMQP_URL:-amqp://guest:guest@mq-<<.Node.Hostname>>:5672}
+      <<: *required-db-env
+      AMQP_URL: ${AMQP_URL:-amqp://${AMQP_USER:-guest}:${AMQP_PASSWORD:-guest}@mq-<<.Node.Hostname>>:5672}
     logging: *default-logging
     deploy: *multi-replicated
   nginx:

ke2/extra/jobmngrd/docker-compose.override.yml

@@ -1,7 +1,11 @@
+# 外部 jobmngrd 構成では KE2.0 本体側で rabbitmqctl add_user により追加した
+# 専用ユーザ・パスワードを AMQP_URL に埋め込んで接続するため、AMQP_URL の指定は必須。
+# 未指定の場合は docker compose 起動時にエラーで停止する (サンプル値が暗黙に
+# 使われて認証失敗するのを防ぐ目的)。
 services:
   jobmngrd:
     logging:
       driver: local
     environment:
-      - AMQP_URL=${AMQP_URL:-amqps://kompira:kompira@${AMQP_HOST:-rabbitmq}:5671}
+      AMQP_URL: '${AMQP_URL:?AMQP_URL must be set: e.g., amqps://<user>:<password>@<rabbitmq-host>:5671}'
     restart: always

ke2/services/jobmngrd.yml

@@ -4,9 +4,9 @@ services:
     hostname: jm-${HOSTNAME:?HOSTNAME must be set}
     init: true
     environment:
-      DATABASE_URL: ${DATABASE_URL:-pgsql://kompira:kompira@${DATABASE_HOST:-postgres}:5432/kompira}
+      DATABASE_URL: ${DATABASE_URL:-pgsql://${DATABASE_USER:-kompira}:${DATABASE_PASSWORD:-kompira}@${DATABASE_HOST:-postgres}:5432/${DATABASE_NAME:-kompira}}
       CACHE_URL: ${CACHE_URL:-redis://redis:6379}
-      AMQP_URL: ${AMQP_URL:-amqp://guest:guest@rabbitmq:5672}
+      AMQP_URL: ${AMQP_URL:-amqp://${AMQP_USER:-guest}:${AMQP_PASSWORD:-guest}@rabbitmq:5672}
       TZ: ${TZ:-Asia/Tokyo}
       LOGGING_NAME: jobmngrd
       LOGGING_STREAM: ${JOBMNGRD_LOGGING_STREAM:-${LOGGING_STREAM:-true}}

ke2/services/kompira.yml

@@ -15,8 +15,8 @@ x-kompira-common-settings:
 
 x-kompira-common-environ:
   &kompira-common-environ
-  DATABASE_URL: ${DATABASE_URL:-pgsql://kompira:kompira@${DATABASE_HOST:-postgres}:5432/kompira}
-  AMQP_URL: ${AMQP_URL:-amqp://guest:guest@rabbitmq:5672}
+  DATABASE_URL: ${DATABASE_URL:-pgsql://${DATABASE_USER:-kompira}:${DATABASE_PASSWORD:-kompira}@${DATABASE_HOST:-postgres}:5432/${DATABASE_NAME:-kompira}}
+  AMQP_URL: ${AMQP_URL:-amqp://${AMQP_USER:-guest}:${AMQP_PASSWORD:-guest}@rabbitmq:5672}
   CACHE_URL: ${CACHE_URL:-redis://redis:6379}
   LANGUAGE_CODE: ${LANGUAGE_CODE:-ja}
   TZ: ${TZ:-Asia/Tokyo}

ke2/services/nginx.yml

@@ -3,10 +3,10 @@ services:
     image: registry.hub.docker.com/library/nginx:1.27-alpine
     hostname: nx-${HOSTNAME:?HOSTNAME must be set}
     environment:
-      - TZ=${TZ:-Asia/Tokyo}
-      - NGINX_ENVSUBST_FILTER=^KOMPIRA
-      - KOMPIRA_HOST=${KOMPIRA_HOST:-kompira}
-      - KOMPIRA_PORT=${KOMPIRA_PORT:-8000}
+      TZ: ${TZ:-Asia/Tokyo}
+      NGINX_ENVSUBST_FILTER: ^KOMPIRA
+      KOMPIRA_HOST: ${KOMPIRA_HOST:-kompira}
+      KOMPIRA_PORT: ${KOMPIRA_PORT:-8000}
     configs:
       # MEMO: /etc/nginx/templates/*.template は起動時に環境変数が展開されて /etc/nginx/conf.d/* に書き出される
       - source: nginx-config

ke2/services/postgres.yml

@@ -4,8 +4,13 @@ services:
     image: registry.hub.docker.com/library/postgres:16.3-alpine
     hostname: db-${HOSTNAME:?HOSTNAME must be set}
     environment:
-      POSTGRES_PASSWORD: kompira
-      POSTGRES_USER: kompira
+      # POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB は **PGDATA ボリュームが空の初回起動時のみ**
+      # 反映される (公式 postgres イメージの仕様)。後から DATABASE_USER / DATABASE_PASSWORD /
+      # DATABASE_NAME を変更しても DB 内のユーザ・パスワード・データベース名は更新されない。
+      # 既存環境で変更したい場合の手順は管理者マニュアル「資格情報管理」章を参照。
+      POSTGRES_USER: ${DATABASE_USER:-kompira}
+      POSTGRES_PASSWORD: ${DATABASE_PASSWORD:-kompira}
+      POSTGRES_DB: ${DATABASE_NAME:-kompira}
       TZ: ${TZ:-Asia/Tokyo}
     volumes:
       - ${PGDATA:-kompira_pg16}:/var/lib/postgresql/data

ke2/services/rabbitmq.yml

@@ -4,6 +4,12 @@ services:
     hostname: mq-${HOSTNAME:?HOSTNAME must be set}
     environment:
       RABBITMQ_DATA_DIR: /var/lib/rabbitmq
+      # RABBITMQ_DEFAULT_USER / RABBITMQ_DEFAULT_PASS は **rabbitmq データボリュームが空の初回起動時のみ**
+      # 反映される (公式 rabbitmq イメージの仕様)。後から AMQP_USER / AMQP_PASSWORD を変更しても
+      # rabbitmq のユーザ・パスワードは更新されない。既存環境で変更したい場合の手順は
+      # 管理者マニュアル「資格情報管理」章を参照 (rabbitmqctl change_password 等)。
+      RABBITMQ_DEFAULT_USER: ${AMQP_USER:-guest}
+      RABBITMQ_DEFAULT_PASS: ${AMQP_PASSWORD:-guest}
       TZ: ${TZ:-Asia/Tokyo}
     configs:
       - source: bootstrap-rabbitmq

ke2/services/redis.yml

@@ -3,4 +3,4 @@ services:
     image: registry.hub.docker.com/library/redis:7.2-alpine
     hostname: re-${HOSTNAME:?HOSTNAME must be set}
     environment:
-      - TZ=${TZ:-Asia/Tokyo}
+      TZ: ${TZ:-Asia/Tokyo}