Yapılandırma¶
Yapılandırma tipli olarak şu öncelikle yüklenir:
- İşletim sistemi ortam değişkenleri
- Varsa
.envdosyası - Güvenli varsayılanlar
Gerçek bir .env dosyasını asla commit etmeyin. Şablon olarak .env.example kullanın.
Önemli gruplar:
- Uygulama kimliği:
APP_NAME,APP_ENV,APP_VERSION,INSTANCE_ID - HTTP ve zaman aşımları
- CORS
- TLS modu ve sertifika yolları
- MongoDB URI, veritabanı, zaman aşımları, havuz boyutları
- Kimlik doğrulama:
AUTH_ENABLED,AUTH_CLIENT_ID,AUTH_CLIENT_SECRET,AUTH_JWT_SECRET,AUTH_ISSUER,AUTH_AUDIENCE,AUTH_ACCESS_TOKEN_TTL,AUTH_TOKEN_MAX_BODY_BYTES - Integration actor:
INTEGRATION_ACTOR_USER_ID - Kiracı varsayılanları:
DEFAULT_COMPANY_ID,DEFAULT_ORGANIZATION_ID - Idempotency:
IDEMPOTENCY_ENABLED,IDEMPOTENCY_REQUIRED,IDEMPOTENCY_RETENTION_HOURS,IDEMPOTENCY_PROCESSING_LEASE_SECONDS - İstek arşivi:
REQUEST_ARCHIVE_ENABLED,REQUEST_ARCHIVE_REQUIRED,REQUEST_ARCHIVE_RETENTION_DAYS,REQUEST_ARCHIVE_STORE_RAW_BODY - Worker ve health push yer tutucuları
AUTH_ENABLED=true iken client ID, client secret, JWT secret, issuer, audience ve TTL geçerli değilse uygulama fail-fast ile açılmaz. Client secret ile JWT secret farklı olmalı ve en az 32 karakter/byte olmalıdır.
INTEGRATION_ACTOR_USER_ID¶
Gelen iş emri kalıcılığı denetim alanları için zorunlu yapılandırma.
| Özellik | Değer |
|---|---|
| Amaç | Proje/ürün denetim alanlarında kullanılan mevcut aktif kullanıcının _id değeri |
| Biçim | Gerçek kullanıcı belgesinin 24 karakter hexadecimal MongoDB ObjectID’si — rastgele üretilmiş ID değil |
| Secret mı? | Hayır (yine de loglanmaz ve API yanıtına yazılmaz) |
| Kiracı | Çalışma zamanında istek kiracısıyla aynı company/organization altında olmalıdır |
| Boş / geçersiz biçim | Başlangıçta fail-fast (zorunlu + 24-hex) |
| Kalıcılık | check ve canlı inbound POST kullanıcının var ve aktif olduğunu doğrular; kiracı eşleşmesi yalnızca istek anında |
Güvenli tanı çıktıları auth_enabled, auth_client_id, auth_issuer, auth_audience, auth_access_token_ttl ve integration_actor_configured (boolean) alanlarını gösterir. Aktör ObjectID loglanmaz. Secret’lar asla loglanmaz.
Kullanım ayrıntıları için Kimlik Doğrulama ve İş Emri Kalıcılığı sayfalarına bakın.
DEFAULT_COMPANY_ID ve DEFAULT_ORGANIZATION_ID¶
Inbound iş emri istekleri ve outbound GET uç noktaları hem company_id hem organization_id atladığında kullanılan isteğe bağlı ortam düzeyi kiracı varsayılanları.
| Özellik | Değer |
|---|---|
| Amaç | Inbound POST ve outbound GET API'leri için geri dönüş kiracı çifti |
| Biçim | 24 karakter hexadecimal MongoDB ObjectID dizesi |
| Secret mı? | Hayır |
| Çift kuralı | Her ikisi boş olmalı veya her ikisi geçerli ObjectID olmalı |
| Yalnızca biri set | Başlangıçta fail-fast yapılandırma hatası |
| Çalışma zamanı kısmi istek | Tam olarak bir istek/sorgu değeri → 400 TENANT_CONTEXT_INCOMPLETE (varsayılanlar uygulanmaz) |
Her ikisi boş olduğunda çağıranlar her istekte kiracı çiftini sağlamalıdır. Her ikisi set olduğunda tek kiracılı dağıtımlar payload ve sorgu dizelerinden kiracı alanlarını atlayabilir.
Bkz. Inbound İş Emirleri, Makine Olayları ve Üretim Performansı.
Idempotency ve istek arşivi¶
| Değişken | Varsayılan | Not |
|---|---|---|
IDEMPOTENCY_ENABLED |
true |
Live idempotency ana anahtarı |
IDEMPOTENCY_REQUIRED |
true |
Etkin iken live endpointte Idempotency-Key zorunlu |
IDEMPOTENCY_RETENTION_HOURS |
720 |
Pozitif tamsayı; document expires_at |
IDEMPOTENCY_PROCESSING_LEASE_SECONDS |
300 |
Min 30, max 3600 |
REQUEST_ARCHIVE_ENABLED |
true |
Inbound work-order attempt arşivi |
REQUEST_ARCHIVE_REQUIRED |
true |
İlk archive insert başarısızsa 503 |
REQUEST_ARCHIVE_RETENTION_DAYS |
90 |
Pozitif tamsayı |
REQUEST_ARCHIVE_STORE_RAW_BODY |
true |
Limit içinde raw body sakla |
Geçersiz değerler başlangıçta fail-fast olur. Tam Idempotency-Key INFO loglarına yazılmaz. Secret’ler redakte edilir.
Bkz. Idempotency ve İstek Arşivi.
Çalışma Zamanı Yapılandırma Yolları¶
Windows¶
Yerel Windows Servisi olarak dağıtıldığında (önerilen):
text
C:\IQVizyon\IQVIntegrationAPI\
bin\ # Uygulama ikili dosyası
config\ # Yapılandırma dizini
.env # Ortam dosyası
logs\ # Uygulama günlükleri
backups\ # Güncelleme öncesi yedekler
deployment\ # Dağıtım meta verileri
Servis yapılandırmasını C:\IQVizyon\IQVIntegrationAPI\config\.env dosyasından yükler.
Linux¶
systemd servisi olarak dağıtıldığında:
```text /opt/iqvizyon/iqv-integration-api/ bin/ # Uygulama ikili dosyası deployment/ # Dağıtım meta verileri
/etc/iqvizyon/iqv-integration-api.env # Ortam dosyası
/var/log/iqvizyon/iqv-integration-api/ # Uygulama günlükleri
/var/lib/iqvizyon/iqv-integration-api/ backups/ # Güncelleme öncesi yedekler ```
Servis yapılandırmasını /etc/iqvizyon/iqv-integration-api.env dosyasından yükler.
--env-file Bayrağı¶
İkili dosya, ortam dosyası konumunu belirtmek için --env-file bayrağını kabul eder:
bash
./iqv-integration-api service install --env-file /etc/iqvizyon/iqv-integration-api.env
./iqv-integration-api service run --env-file /etc/iqvizyon/iqv-integration-api.env
powershell
.\iqv-integration-api.exe service install --env-file C:\IQVizyon\IQVIntegrationAPI\config\.env
.\iqv-integration-api.exe service run --env-file C:\IQVizyon\IQVIntegrationAPI\config\.env
Docker¶
Windows Docker genelde operatör .env / -EnvFile dosyasını proje dizininden veya açık yoldan bağlar. Linux Docker üretim yolu /etc/iqvizyon/iqv-integration-api.docker.env kullanır (paket örneği + CLI; varsa üzerine yazılmaz).
Konteyner içinde HTTP_HOST 0.0.0.0 kalmalıdır. Dışarı yayın HostPort iledir; HTTP_HOST genel bir hostname yapılmaz. PUBLIC_BASE_URL dışarıdan görünen URL’dir (host + HostPort).
Bkz. Docker Kurulumu.
Env dosyasını kim oluşturur
Windows kurucuları .env otomatik oluşturmaz. Önce .env.example kopyalayın.
Linux üretim install.sh paket örneği + CLI ile /etc/iqvizyon/iqv-integration-api.env (veya Docker env yolu) oluşturabilir. Mevcut dosyanın üzerine yazılmaz.
Yapılandırma alan matrisi¶
Kaynak: internal/config/config.go ve .env.example. Kodda olmayan alan listelenmez. Ortam değişkeni adları İngilizce (kaynak kod ile aynı) tutulur.
| Name | Required | Conditional required | Default | Type | Example | Secret? | Used by | Validation |
|---|---|---|---|---|---|---|---|---|
APP_NAME |
No | — | iqv-integration-api |
string | iqv-integration-api |
No | Identity | — |
APP_ENV |
No | — | development |
string | production |
No | Identity | — |
APP_VERSION |
No | — | dev |
string | 1.2.3 |
No | Identity | — |
INSTANCE_ID |
No | — | local-development |
string | host-a |
No | Identity | — |
LOG_LEVEL |
No | — | debug |
string | info |
No | Logging | — |
LOG_FORMAT |
No | — | json |
string | json |
No | Logging | — |
HTTP_HOST |
No | — | 0.0.0.0 |
string | 0.0.0.0 |
No | HTTP | — |
HTTP_PORT |
No | — | 8080 |
int | 4242 |
No | HTTP / installers | Positive port |
API_PREFIX |
No | — | /api/v1 |
string | /api/v1 |
No | HTTP | — |
PUBLIC_BASE_URL |
No | — | http://localhost:8080 |
URL string | https://api.example |
No | HTTP | — |
HTTP_READ_TIMEOUT |
No | — | 15s |
duration | 15s |
No | HTTP | Parseable duration |
HTTP_READ_HEADER_TIMEOUT |
No | — | 10s |
duration | 10s |
No | HTTP | Parseable duration |
HTTP_WRITE_TIMEOUT |
No | — | 30s |
duration | 30s |
No | HTTP | Parseable duration |
HTTP_IDLE_TIMEOUT |
No | — | 60s |
duration | 60s |
No | HTTP | Parseable duration |
HTTP_SHUTDOWN_TIMEOUT |
No | — | 20s |
duration | 20s |
No | HTTP / systemd | Parseable duration |
HTTP_REQUEST_TIMEOUT |
No | — | 30s |
duration | 30s |
No | HTTP | Parseable duration |
HTTP_MAX_BODY_BYTES |
No | — | 10485760 |
int64 | 10485760 |
No | HTTP | Non-negative |
INBOUND_MAX_BODY_BYTES |
No | — | 10485760 |
int64 | 10485760 |
No | Inbound | Non-negative |
INBOUND_MAX_PROJECTS_PER_REQUEST |
No | — | 100 |
int | 100 |
No | Inbound | Positive |
CORS_ENABLED |
No | — | false |
bool | true |
No | CORS | Bool |
CORS_ALLOWED_ORIGINS |
No | When CORS enabled | empty | CSV | https://a.com |
No | CORS | CSV list |
CORS_ALLOWED_METHODS |
No | — | GET,POST,… | CSV | … | No | CORS | CSV list |
CORS_ALLOWED_HEADERS |
No | — | Authorization,… | CSV | … | No | CORS | CSV list |
CORS_ALLOW_CREDENTIALS |
No | — | false |
bool | false |
No | CORS | Bool |
TLS_MODE |
No | — | disabled |
enum string | disabled |
No | TLS | Known modes |
TLS_CERT_FILE |
No | When TLS enabled | empty | path | /etc/ssl/cert.pem |
No | TLS | Path when required |
TLS_KEY_FILE |
No | When TLS enabled | empty | path | /etc/ssl/key.pem |
Yes (file) | TLS | Path when required |
MONGODB_URI |
Yes (runtime) | — | mongodb://127.0.0.1:27017 |
URI | mongodb://host:27017 |
Yes | Mongo / check / serve | Non-empty at serve; Docker installers reject localhost inside container |
MONGODB_DATABASE |
No | — | champion |
string | champion |
No | Mongo | — |
MONGODB_CONNECT_TIMEOUT |
No | — | 10s |
duration | 10s |
No | Mongo | Duration |
MONGODB_PING_TIMEOUT |
No | — | 5s |
duration | 5s |
No | Mongo | Duration |
MONGODB_OPERATION_TIMEOUT |
No | — | 15s |
duration | 15s |
No | Mongo | Duration |
MONGODB_MAX_POOL_SIZE |
No | — | 100 |
int | 100 |
No | Mongo | ≥ 0 |
MONGODB_MIN_POOL_SIZE |
No | — | 5 |
int | 5 |
No | Mongo | ≥ 0 |
AUTH_ENABLED |
No | — | false |
bool | true |
No | Auth | Bool |
AUTH_CLIENT_ID |
No | When AUTH_ENABLED=true |
empty | string | iqv-standard-integration |
No | Auth | Required if auth on |
AUTH_CLIENT_SECRET |
No | When auth on | empty | string | (secret) | Yes | Auth | ≥32 chars; ≠ JWT secret |
AUTH_JWT_SECRET |
No | When auth on | empty | string | (secret) | Yes | Auth | ≥32 bytes; ≠ client secret |
AUTH_ISSUER |
No | When auth on | iqv-integration-api |
string | … | No | Auth | Required if auth on |
AUTH_AUDIENCE |
No | When auth on | iqv-integration-api |
string | … | No | Auth | Required if auth on |
AUTH_ACCESS_TOKEN_TTL |
No | — | 60m |
duration | 60m |
No | Auth | Duration |
AUTH_TOKEN_MAX_BODY_BYTES |
No | — | 16384 |
int64 | 16384 |
No | Auth | Positive |
INTEGRATION_ACTOR_USER_ID |
Yes | — | empty | ObjectId | 507f… |
No | Inbound audit | 24-hex ObjectId |
DEFAULT_COMPANY_ID |
No | Pair with org | empty | ObjectId | 507f… |
No | Tenant | Both empty or both valid |
DEFAULT_ORGANIZATION_ID |
No | Pair with company | empty | ObjectId | 507f… |
No | Tenant | Both empty or both valid |
IDEMPOTENCY_ENABLED |
No | — | true |
bool | true |
No | Idempotency | Bool |
IDEMPOTENCY_REQUIRED |
No | — | true |
bool | true |
No | Idempotency | Bool |
IDEMPOTENCY_RETENTION_HOURS |
No | — | 720 |
int | 720 |
No | Idempotency | Positive |
IDEMPOTENCY_PROCESSING_LEASE_SECONDS |
No | — | 300 |
int | 300 |
No | Idempotency | 30–3600 |
REQUEST_ARCHIVE_ENABLED |
No | — | true |
bool | true |
No | Archive | Bool |
REQUEST_ARCHIVE_REQUIRED |
No | — | true |
bool | true |
No | Archive | Bool |
REQUEST_ARCHIVE_RETENTION_DAYS |
No | — | 90 |
int | 90 |
No | Archive | Positive |
REQUEST_ARCHIVE_STORE_RAW_BODY |
No | — | true |
bool | true |
No | Archive | Bool |
WORKER_ENABLED |
No | — | false |
bool | false |
No | Worker scaffold | Bool |
WORKER_TIMEZONE |
No | — | UTC |
string | UTC |
No | Worker | — |
OUTBOUND_CRON |
No | — | */5 * * * * |
cron | … | No | Worker | — |
OUTBOUND_BATCH_SIZE |
No | — | 100 |
int | 100 |
No | Worker | — |
OUTBOUND_MAX_RETRY |
No | — | 6 |
int | 6 |
No | Worker | — |
OUTBOUND_TIMEOUT |
No | — | 30s |
duration | 30s |
No | Worker | Duration |
HEALTH_DETAILS_ENABLED |
No | — | false |
bool | false |
No | Health | Bool |
HEALTH_PUSH_ENABLED |
No | — | false |
bool | false |
No | Health push | Bool |
HEALTH_PUSH_URL |
No | When push enabled | empty | URL | … | No | Health push | — |
HEALTH_PUSH_INTERVAL |
No | — | 60s |
duration | 60s |
No | Health push | Duration |
HEALTH_PUSH_TIMEOUT |
No | — | 10s |
duration | 10s |
No | Health push | Duration |
HEALTH_PUSH_BEARER_TOKEN |
No | When push enabled | empty | string | (secret) | Yes | Health push | Redacted in logs |