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/wikialtındaki REST API’sidir; bir Atlassian hesap e-postası ve bir API token ile kimlik doğrular. - Data Center 7.9 ve sonrası,
<base URL>/rest/apialtı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 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.254dahil — artı belirtilmemiş ve multicast adresleri,255.255.255.255’i de içeren ayrılmış240.0.0.0/4bloğ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’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 — 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ı. 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.
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.
- Kaynağı Edit edin ve Confluence webhook kutusunda Turn on’u seçin; URL’yi ve secret’ı kopyalayın.
- 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ı olanX-Hub-Signature: sha256=<HMAC-SHA256 of that exact body>header’ı gider. Data Center olay adını (page_updated, …) en üst düzeydeki bireventalanına koyun: böyle bir alanı olmayan gövde, yorumlar ve etiketler dahil, her teslimatta bir çalıştırmayı kuyruğa alır. - Yanlış imzalanan her şey
401 invalid_signatureile 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ı 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). 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 |