# Confluence

> Confluence Cloud ya da Data Center'ı indekslemek — dağıtım farkları, token türleri, özel adres sınırı ve Data Center webhook'u.

- Güncelleme: 2026-11-04
- Kaynak: https://contextator.com/tr/docs/confluence/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
Bir Confluence Cloud sitesini ya da bir Confluence Data Center örneğini indeksleyin: hesabın
okuyabildiği her space, ya da tam olarak sizin adlandırdığınız space'ler, Confluence'ın storage
formatından Markdown'a render edilir.

## Bir tane eklemek

**Add source → Confluence**

| Alan | Notlar |
|-------|-------|
| **Name** | Mount öneki. Değiştirilemez |
| **Deployment** | *Confluence Cloud* ya da *Confluence Data Center 7.9 or later*. Algılanmaz — ikisi farklı kimlik doğrular ve yanlış bir tahmin, kimlik bilgisini yanlış yöne gönderir |
| **Site URL** | Cloud: `/wiki` yoluyla birlikte, ör. `https://acme.atlassian.net/wiki`. Data Center: kullanıcılarınızın açtığı adres, varsa context path'iyle birlikte, ör. `https://intranet.example.com/confluence` |
| **Account e-mail** | Yalnızca Cloud — API token'ının ait olduğu Atlassian hesabı |
| **API token** / **Personal access token** | Cloud: bir API token'ı. Data Center: bir personal access token. `SECRET_KEY` ile şifreli saklanır, bir daha gösterilmez ve API tarafından asla döndürülmez |
| **Spaces** | Space anahtarları, satır başına bir tane (`ENG`, `OPS`). Hesabın okuyabildiği her space'i indekslemek için boş bırakın |

Kaynak kaydedildikten sonra satırındaki **Test**'e (ya da **Edit** diyaloğundaki **Test connection**'a) basın:
hiçbir şeyi indekslemeden siteyi, kimlik bilgisini ve kapsamı kontrol eder. Her iki durumda da dış sınır hesabın kendi izinleridir: Contextator,
hesabın okuyamadığı bir sayfayı asla görmez.

## Cloud ya da Data Center

- **Cloud**, `https://<site>.atlassian.net/wiki` altındaki REST API'sidir; bir Atlassian hesap
  e-postası ve bir [API token](https://id.atlassian.com/manage-profile/security/api-tokens) ile
  kimlik doğrular.
- **Data Center 7.9 ve sonrası**, `<base URL>/rest/api` altındaki REST API'sidir; bearer olarak
  gönderilen bir personal access token ile kimlik doğrular — e-posta yoktur. Herhangi bir kimlik
  bilgisi gönderilmeden önce, sunucunun sürümü onun anonim application manifest'inden okunur; daha
  eski bir sürüm, okunamayan bir sürüm ya da Confluence olmayan bir sunucu, **sürüm adlandırılarak**
  hem **Test connection**'da hem de senkronizasyonda reddedilir.
- Data Center'dan önceki ürün hattı olan **Confluence Server** desteklenmez. Kullandığınız buysa,
  space'i dışa aktarın ve bunun yerine bir [Yükleme](/tr/docs/upload-source/) kaynağı olarak ekleyin.

## Dahili ağdaki bir Data Center

Base URL bir editör tarafından yazılır ve sunucu ona kaynağın token'ını taşıyarak bağlanır, bu yüzden
bir Confluence kaynağının nereye bağlanabileceği sınırlıdır:

- **Her zaman reddedilir:** loopback ve link-local adresleri — bulut metadata adresi
  `169.254.169.254` dahil — artı belirtilmemiş ve multicast adresleri, `255.255.255.255`'i de içeren ayrılmış
  `240.0.0.0/4` bloğu, ve bunlardan birini taşıyan IPv6 biçimleri (IPv4-eşlenmiş, çevrilmiş, uyumlu ve NAT64). Hiçbir ayar bunları kaldırmaz.
- **İzin verilmedikçe reddedilir:** özel adresler — `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`,
  `100.64.0.0/10` (carrier-grade NAT'ın kullandığı paylaşımlı adres alanı), `198.18.0.0/15` (benchmark),
  `fc00::/7`, ve kullanımdan kaldırılmış site-local aralığı `fec0::/10`.

Data Center'ınız özel bir adrese çözümleniyorsa, host'unu `SOURCE_ALLOWED_HOSTS`'a ekleyin ve
yeniden başlatın:

```
SOURCE_ALLOWED_HOSTS=wiki.corp.example
```

Kontrol, bağlantının gerçekte kullandığı adres üzerinde çalışır — DNS'ten sonra, ve her yönlendirmede
yeniden — böylece ne içeri çözümlenen herkese açık görünümlü bir ad, ne de dahili bir adrese yönlendirme bunu
atlatabilir. Bir ret, kuralı kaynağın satırında ve Test mesajında adlandırır, örneğin:

```
refused: `wiki.corp.example` resolves to a private address; list `wiki.corp.example` in SOURCE_ALLOWED_HOSTS to allow it
```

Bu durumda hiçbir istek — ve dolayısıyla hiçbir token — gönderilmez. Liste yalnızca özel adres
kuralını, ve yalnızca üzerindeki adlar için kaldırır; kontrolü tamamen kapatan bir anahtar yoktur.
`SOURCE_ALLOWED_HOSTS`, ürünle gelen
[`.env.example`](https://github.com/Contextator/Contextator/blob/main/.env.example)'in geri kalanıyla
birlikte `.env` içinde ayarlanır.

0.6.0'dan önce bu liste `CONFLUENCE_ALLOWED_HOSTS` adını taşırdı. O ad 1.0.0'da kaldırıldı: boş olmayan bir değer artık
sunucunun başlamasını `SOURCE_ALLOWED_HOSTS`'u adıyla anan bir mesajla durdurur. Yükseltmeden önce host'larını S3 ve GitHub
Enterprise Server kaynaklarına da izin veren `SOURCE_ALLOWED_HOSTS`'a taşıyın.

## Bir sayfa neye dönüşür

Her sayfa, soy ağacına göre iç içe yerleştirilmiş tek bir Markdown dosyasıdır: `<name>/<space key, lowercased>/<parent page>/<page>.md`;
burada her sayfa klasörünün ve dosyasının adı, slug haline getirilmiş başlık artı sayfa id'sinin ilk sekiz karakteridir.

Yalnızca sayfalar indekslenir. Blog gönderileri indekslenmez, webhook'tan gelen blog olayları yok sayılır.

Confluence'ın storage formatı, XHTML artı Confluence'ın kendi `ac:` ve `ri:` ad alanlarıdır. `.html`
dosyalarının geçtiği aynı HTML→Markdown dönüşümünden geçer — bkz.
[İçerik Türleri](/tr/docs/content-types/) — bu yüzden tablolar, kod blokları, görev listeleri ve
uyarı kutuları yapı olarak hayatta kalır.

- **Makrolar açılır.** Bir expand'in ya da panel'in içindeki metin indekslenir; makronun kendi
  yapılandırması indekslenmez.
- **Uyarı kutuları, onları uyarı kutusu yapan sözcüğü korur**, bu yüzden bir not hâlâ not olarak
  okunur.
- **Kod blokları hayatta kalır.** Sıradan bir HTML ayrıştırıcısının göz ardı ettiği
  `<![CDATA[…]]>` içinde yaşarlar — bu, dönüşüm çalışmadan önce ele alınır, sonra değil.

## Nasıl taze tutulur

Bir Confluence kaynağının zamanlanmış kontrolü **tek bir istektir**: çalıştırmanın indekslediği
tam olarak space'ler üzerinde bir CQL araması, kaç sayfa olduğunu ve en yenisine en son ne zaman
dokunulduğunu bildirir. İkisi de değişmediyse hiçbir şey çekilmez.

**Data Center**'da, bir sayfa değişir değişmez imzalı bir webhook bir senkronizasyon başlatabilir —
bkz. [Push Webhook'ları](/tr/docs/push-webhooks/#confluence-data-center). Senkronizasyon aralığını
tamamlar; onun yerine geçmez. Confluence Cloud bir Forge ya da Connect uygulaması olmadan bir webhook
gönderemez, bu yüzden orada kaynağın taze kalma yolu senkronizasyon
aralığıdır — bkz. [İndeksleme](/tr/docs/indexing/).

### Confluence Cloud için bir relay

Contextator böyle bir şey sunmaz ve Cloud webhook'u kapsam dışında kalır. Cloud'da yine de daha
hızlı güncelleme istiyorsanız, Contextator'ın sunduğu kısım alıcı uçtur ve teslimatın nereden geldiği onu
ilgilendirmez: Cloud tarafında bir Forge ya da Connect uygulamasının beslediği, kendinize ait küçük bir
servis, bir Data Center örneğinin kullanacağı aynı endpoint'e post edebilir.

1. Kaynağı **Edit** edin ve *Confluence webhook* kutusunda **Turn on**'u seçin; URL'yi ve secret'ı kopyalayın.
2. Relay, Cloud olayını alır ve `POST /api/webhooks/confluence/<source-id>` gönderir; gövde olarak olayın
   JSON'u, ayrıca secret ile anahtarlanmış, o gövdenin birebir HMAC-SHA256'sı olan
   `X-Hub-Signature: sha256=<HMAC-SHA256 of that exact body>` header'ı gider. Data Center olay adını
   (`page_updated`, …) en üst düzeydeki bir `event` alanına koyun: böyle bir alanı olmayan gövde, yorumlar
   ve etiketler dahil, her teslimatta bir çalıştırmayı kuyruğa alır.
3. Yanlış imzalanan her şey `401 invalid_signature` ile reddedilir; hangi olayların bir çalıştırmayı
   kuyruğa alacağına ve çalıştırmalar arasındaki asgari aralığa dair kurallar
   [Push Webhook'ları](/tr/docs/push-webhooks/#confluence-data-center) sayfasındakilerdir.

Relay'i kurmak, barındırmak ve güvenceye almak size aittir; Contextator onu test etmez. Senkronizasyon
aralığını açık tutun: bir teslimat yakında bakmak için bir ipucudur, neyin değiştiğinin kaydı asla.

## Bilinmesi gereken sınırlar

- **Bir kaynak varsayılan olarak en fazla 5.000 sayfa indeksler.** Tavan `CONFLUENCE_MAX_PAGES`'tir (1 ile 100 000 arası, instance başına ayarlanır — bkz. [Yapılandırma](/tr/docs/configuration/)). Daha büyük bir wiki, tavana kadar indekslenir ve
  çalıştırma bunu, tam olarak bu sözlerle, kaynağın satırında söyler. Her birinde daha az space
  adlandırarak birden çok kaynağa bölün.
- **Adlandırılmış birkaç space'ten biri yanıt vermeyi bırakırsa hiçbir şey silinmez.** Yeniden
  adlandırılmış bir space anahtarı ya da hesaptan geri alınmış bir izin, API'ye hatasız, sayfası
  olmayan bir space olarak okunur — bu yüzden az önce belge tutan ama şimdi hiçbirini sunmayan
  yapılandırılmış bir space, belgelerini sessizce silmek yerine, space'i adlandırarak
  **senkronizasyonu başarısız kılar**. **Spaces** boş bırakıldığında orada ne olması gerektiğine dair
  bir liste yoktur ve bu kontrol yapılamaz.
- **Render edilemeyen bir sayfa bir şikâyettir, başarısız bir senkronizasyon değil.** Başarısız olan
  bir istek başarısız bir senkronizasyondur. İkisi ayrı tutulur, böylece rate-limit'e takılan bir ilk
  çekim, eksik bir wiki'nin üçte biri üzerinden başarı bildiremez.

## Sık karşılaşılan sorunlar

| Belirti | Neden ve çözüm |
|---------|---------------|
| **Test connection**, bir sürüm adlandırarak reddediyor | Sunucu 7.9'dan eski, sürümü okunamadı ya da hiç Confluence değil |
| Ret: özel bir adrese çözümleniyor | Data Center'ın host'unu `SOURCE_ALLOWED_HOSTS`'a ekleyin ve yeniden başlatın |
| Yapılandırılmış bir space, adını anarak senkronizasyonu başarısız kılıyor | Space anahtarı yeniden adlandırıldı, ya da hesabın üzerindeki izni geri alındı |
| Bir sayfa eksik ama senkronizasyon başarılı oldu | Render edilemez olarak reddedildi, başarısız bir senkronizasyona neden olmadı — şikâyet için kaynağın satırına bakın |
| **Spaces** boş bırakıldığında hiçbir şey indekslenmedi | Hesabın hiçbir space üzerinde okuma izni yok |
| **Test connection** ya da senkronizasyon, site URL'sini adlandırarak `404` yanıtı veriyor | Site URL'sinde `/wiki` yolu (Cloud) ya da context path'i (Data Center) eksik — hata hangisinin kontrol edileceğini adlandırır |
