chore(env): split dev/prod env files and clarify keycloak settings

.env.development

@@ -8,17 +8,23 @@ DB_NAME=member_center
 DB_USER=member_ose
 DB_PASSWORD=Dmrax5bKDf
 
-# Keycloak (preferred when KEYCLOAK_BASE_URL + KEYCLOAK_REALM are set)
+# Keycloak 參數說明：
+# - KEYCLOAK_ISSUER 必須與 token 的 iss 完全一致（建議填公開網址）。
+# - KEYCLOAK_BASE_URL 是後端對 Keycloak 的基底網址（development 統一走公開入口）。
+# - KEYCLOAK_JWKS_URL / KEYCLOAK_TOKEN_ENDPOINT / KEYCLOAK_USERINFO_ENDPOINT 可明確覆寫端點。
+# - KEYCLOAK_AUDIENCE 可選，但建議設定以啟用 aud 驗證。
+# - KEYCLOAK_CLIENT_* 給 /auth/oidc/exchange 與 /auth/refresh 使用。
+# - KEYCLOAK_ADMIN_CLIENT_* 給 Keycloak Admin API 同步流程使用。
 KEYCLOAK_BASE_URL=https://auth.ose.tw/
 KEYCLOAK_REALM=master
 KEYCLOAK_VERIFY_TLS=true
-KEYCLOAK_ISSUER=
+KEYCLOAK_ISSUER=https://auth.ose.tw/realms/master
-KEYCLOAK_JWKS_URL=
+KEYCLOAK_JWKS_URL=https://auth.ose.tw/realms/master/protocol/openid-connect/certs
 KEYCLOAK_AUDIENCE=
 KEYCLOAK_CLIENT_ID=member-frontend
 KEYCLOAK_CLIENT_SECRET=bp2I0HWyz5cjcu5RGnBPXNC2vjCdckkv
-KEYCLOAK_TOKEN_ENDPOINT=
+KEYCLOAK_TOKEN_ENDPOINT=https://auth.ose.tw/realms/master/protocol/openid-connect/token
-KEYCLOAK_USERINFO_ENDPOINT=
+KEYCLOAK_USERINFO_ENDPOINT=https://auth.ose.tw/realms/master/protocol/openid-connect/userinfo
 KEYCLOAK_ADMIN_CLIENT_ID=member-backend
 KEYCLOAK_ADMIN_CLIENT_SECRET=hat8BmxlP0eZ7CXuKbV4HwQ3abLHzAJ9
 KEYCLOAK_ADMIN_REALM=master

.env.example

@@ -1,35 +0,0 @@
-# memberapi.ose.tw backend env (development)
-APP_ENV=development
-PORT=8000
-
-DB_HOST=postgresql
-DB_PORT=5432
-DB_NAME=member.ose.tw
-DB_USER=member_ose
-DB_PASSWORD=Dmrax5bKDf
-
-# Keycloak (preferred when KEYCLOAK_BASE_URL + KEYCLOAK_REALM are set)
-KEYCLOAK_BASE_URL=https://auth.ose.tw/
-KEYCLOAK_REALM=master
-KEYCLOAK_VERIFY_TLS=true
-KEYCLOAK_ISSUER=
-KEYCLOAK_JWKS_URL=
-KEYCLOAK_AUDIENCE=
-KEYCLOAK_CLIENT_ID=member-frontend
-KEYCLOAK_CLIENT_SECRET=bp2I0HWyz5cjcu5RGnBPXNC2vjCdckkv
-KEYCLOAK_TOKEN_ENDPOINT=
-KEYCLOAK_USERINFO_ENDPOINT=
-KEYCLOAK_ADMIN_CLIENT_ID=member-backend
-KEYCLOAK_ADMIN_CLIENT_SECRET=hat8BmxlP0eZ7CXuKbV4HwQ3abLHzAJ9
-KEYCLOAK_ADMIN_REALM=master
-
-PUBLIC_FRONTEND_ORIGINS=https://member.ose.tw,https://mkt.ose.tw,https://admin.ose.tw
-INTERNAL_SHARED_SECRET=CHANGE_ME
-MEMBER_REQUIRED_REALM_ROLES=admin,manager
-ADMIN_REQUIRED_REALM_ROLES=admin,manager
-
-# Cache backend: memory | redis
-CACHE_BACKEND=redis
-CACHE_REDIS_URL=redis://cache/0
-CACHE_PREFIX=memberapi
-CACHE_DEFAULT_TTL_SECONDS=30

.env.production

@@ -0,0 +1,41 @@
+# memberapi.ose.tw backend env (development)
+APP_ENV=development
+PORT=8000
+
+DB_HOST=postgresql
+DB_PORT=5432
+DB_NAME=member.ose.tw
+DB_USER=member_ose
+DB_PASSWORD=Dmrax5bKDf
+
+# Keycloak 參數說明：
+# - KEYCLOAK_ISSUER 必須與 token 的 iss 完全一致（建議填公開網址）。
+# - KEYCLOAK_BASE_URL 是後端對 Keycloak 的基底網址（development 統一走公開入口）。
+# - KEYCLOAK_JWKS_URL / KEYCLOAK_TOKEN_ENDPOINT / KEYCLOAK_USERINFO_ENDPOINT 可明確覆寫端點。
+# - KEYCLOAK_AUDIENCE 可選，但建議設定以啟用 aud 驗證。
+# - KEYCLOAK_CLIENT_* 給 /auth/oidc/exchange 與 /auth/refresh 使用。
+# - KEYCLOAK_ADMIN_CLIENT_* 給 Keycloak Admin API 同步流程使用。
+KEYCLOAK_BASE_URL=http://auth_ose_tw:8080
+KEYCLOAK_REALM=master
+KEYCLOAK_VERIFY_TLS=true
+KEYCLOAK_ISSUER=https://auth.ose.tw/realms/master
+KEYCLOAK_JWKS_URL=http://auth_ose_tw:8080/realms/master/protocol/openid-connect/certs
+KEYCLOAK_AUDIENCE=
+KEYCLOAK_CLIENT_ID=member-frontend
+KEYCLOAK_CLIENT_SECRET=bp2I0HWyz5cjcu5RGnBPXNC2vjCdckkv
+KEYCLOAK_TOKEN_ENDPOINT=http://auth_ose_tw:8080/realms/master/protocol/openid-connect/token
+KEYCLOAK_USERINFO_ENDPOINT=http://auth_ose_tw:8080/realms/master/protocol/openid-connect/userinfo
+KEYCLOAK_ADMIN_CLIENT_ID=member-backend
+KEYCLOAK_ADMIN_CLIENT_SECRET=hat8BmxlP0eZ7CXuKbV4HwQ3abLHzAJ9
+KEYCLOAK_ADMIN_REALM=master
+
+PUBLIC_FRONTEND_ORIGINS=https://member.ose.tw,https://mkt.ose.tw,https://admin.ose.tw
+INTERNAL_SHARED_SECRET=CHANGE_ME
+MEMBER_REQUIRED_REALM_ROLES=admin,manager
+ADMIN_REQUIRED_REALM_ROLES=admin,manager
+
+# Cache backend: memory | redis
+CACHE_BACKEND=redis
+CACHE_REDIS_URL=redis://cache/0
+CACHE_PREFIX=memberapi
+CACHE_DEFAULT_TTL_SECONDS=30

README.md

@@ -7,7 +7,7 @@ cd backend
 python -m venv .venv
 source .venv/bin/activate
 pip install -e .
-cp .env.example .env
+# local development uses .env.development directly
 psql "$DATABASE_URL" -f scripts/init_schema.sql
 ./scripts/start_dev.sh
 ```

scripts/start_dev.sh

@@ -3,12 +3,9 @@ set -euo pipefail
 
 cd "$(dirname "$0")/.."
 source .venv/bin/activate
-if [ -f ".env.development" ]; then
+ENV_FILE=".env.development"
-  ENV_FILE=".env.development"
+if [ ! -f "$ENV_FILE" ]; then
-elif [ -f ".env" ]; then
+  echo "missing $ENV_FILE."
-  ENV_FILE=".env"
-else
-  echo "missing .env.development or .env. copy .env.example first."
   exit 1
 fi