diff --git a/.gitignore b/.gitignore index 1927063d5..782049005 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,8 @@ olares-cli-*.tar.gz cli/output daemon/output daemon/bin + +docs/.vitepress/dist/ +docs/.vitepress/cache/ +node_modules +.idea/ \ No newline at end of file diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts new file mode 100644 index 000000000..5ae3d82e2 --- /dev/null +++ b/docs/.vitepress/config.mts @@ -0,0 +1,147 @@ +import { defineConfig,UserConfig,DefaultTheme } from "vitepress"; +import { withMermaid } from "vitepress-plugin-mermaid"; +import { en } from "./en"; +import { zh } from "./zh"; +import _ from "lodash"; +//import defaultConfig from 'vitepress-versioning-plugin'; + + + +function defineVersionedConfig2( + defaultConfig: UserConfig +): UserConfig { + let config = _.defaultsDeep(defaultConfig); + + if( !process.env.BASE_URL || !process.env.VERSIONS || !process.env.LATEST_VERSION ) { + return config; + } + + const versions = process.env.VERSIONS?.split(","); + const latestVersion = process.env.LATEST_VERSION || versions![versions!.length - 1]; + console.log(versions, latestVersion); + + for( const locale of Object.keys(config.locales) ) { + let themeConfig = config.locales[locale]!.themeConfig!; + + themeConfig?.nav?.push( + { + component: 'VersionSwitcher', + // Optional props to pass to the component + props: { + versions, + latestVersion, + } + } + ); + } + + return config; +} + + + +// https://vitepress.dev/reference/site-config +export default defineVersionedConfig2(withMermaid({ + title: "Olares", + description: "Let people own their data again", + lang: "en", + locales: { + root: { + label: "English", + ...en, + }, + zh: { + label: "简体中文", + ...zh, + }, + }, + themeConfig: { + search: { + provider: "algolia", + options: { + appId: "DZ6H2FVQGO", + apiKey: "e5257d88b605dc0e5b82b12854aea9a5", + indexName: "olares", + searchParameters: { + queryLanguages: ["zh", "en"], + }, + locales: { + zh: { + placeholder: "搜索文档", + translations: { + button: { + buttonText: "搜索文档", + buttonAriaLabel: "搜索文档", + }, + modal: { + searchBox: { + resetButtonTitle: "清除查询条件", + resetButtonAriaLabel: "清除查询条件", + cancelButtonText: "取消", + cancelButtonAriaLabel: "取消", + }, + startScreen: { + recentSearchesTitle: "搜索历史", + noRecentSearchesText: "没有搜索历史", + saveRecentSearchButtonTitle: "保存至搜索历史", + removeRecentSearchButtonTitle: "从搜索历史中移除", + favoriteSearchesTitle: "收藏", + removeFavoriteSearchButtonTitle: "从收藏中移除", + }, + errorScreen: { + titleText: "无法获取结果", + helpText: "你可能需要检查你的网络连接", + }, + footer: { + selectText: "选择", + navigateText: "切换", + closeText: "关闭", + searchByText: "搜索提供者", + }, + noResultsScreen: { + noResultsText: "无法找到相关结果", + suggestedQueryText: "你可以尝试查询", + reportMissingResultsText: "你认为该查询应该有结果？", + reportMissingResultsLinkText: "点击反馈", + }, + }, + }, + }, + }, + }, + }, + }, + + sitemap: { + hostname: "https://docs.olares.com/", + }, + lastUpdated: true, + base: process.env.BASE_URL || "/", + vite: { + build: { + minify: "terser", + chunkSizeWarningLimit: Infinity, + }, + define: { + 'process.env.VERSIONS': JSON.stringify(process.env.VERSIONS || JSON.stringify([])), + 'process.env.LANGUAGES': JSON.stringify(process.env.LANGUAGES || JSON.stringify([])), + } + }, + head: [ + [ + "meta", + { + name: "google-site-verification", + content: "3AzyPY6Q-LxE8CBNwz6ppsqDJ4iQaiPY9V0MHJbQlbU", + }, + ], + // 引入 Material Design Icons + [ + "link", + { + rel: "stylesheet", + href: "https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,200,0..1,-50..200", + }, + ], + ], +})); diff --git a/docs/.vitepress/en.ts b/docs/.vitepress/en.ts new file mode 100644 index 000000000..d5dbab660 --- /dev/null +++ b/docs/.vitepress/en.ts @@ -0,0 +1,804 @@ +import { defineConfig, type DefaultTheme } from "vitepress"; + +const side = { + "/manual/": [ + { + text: "What is Olares", + link: "/manual/docs-home", + items: [ + // A{ text: "Why Olares", link: "/manual/why-olares" }, + //{ text: "Feature comparison", link: "/manual/feature-overview" }, + { text: "Olares architecture", link: "/manual/system-architecture" }, + { text: "Compare Olares and NAS", link: "/manual/olares-vs-nas" }, + { + text: "Help and support", + collapsed: true, + items: [ + { text: "FAQs", link: "/manual/help/faqs" }, + { + text: "Request support", + link: "/manual/help/request-technical-support", + }, + //{ + // text: "Troubleshooting Guide", + // link: "/manual/help/troubleshooting-guide", + // }, + ], + }, + ], + }, + { + text: "Get started", + collapsed: false, + link: "/manual/get-started/", + items: [ + // { text: "Quick start", link: "/manual/get-started/quick-start" }, + { + text: "Create an Olares ID", + link: "/manual/get-started/create-olares-id", + }, + { + text: "Install Olares", + link: "/manual/get-started/install-olares", + }, + { + text: "Back up mnemonics", + link: "/manual/larepass/back-up-mnemonics" + }, + { + text: "What's next", + link: "/manual/get-started/next-steps", + }, + ], + }, + { + text: "LarePass", + link: "/manual/larepass/", + collapsed: true, + items: [ + { + text: "Manage accounts", + collapsed: true, + items: [ + {text: "Create accounts", link:"/manual/larepass/create-account"}, + {text: "Back up mnemonics", link: "/manual/larepass/back-up-mnemonics"}, + {text: "Manage integrations", link:"/manual/larepass/integrations"}, + ], + }, + {text: "Manage VPN", link:"/manual/larepass/private-network"}, + { + text: "Manage device", + collapsed: true, + items: [ + {text: "Activate Olares", link:"/manual/larepass/activate-olares"}, + {text: "Manage Olares", link:"/manual/larepass/manage-olares"}, + ], + }, + { + text: "Manage files", + collapsed: true, + items: [ + {text: "Common file operations", link:"/manual/larepass/manage-files"}, + {text: "Sync and share", link:"/manual/larepass/sync-share"} + ] + }, + { + text: "Manage passwords", + collapsed: true, + items: [ + {text: "Autofill passwords", link: "/manual/larepass/autofill"}, + {text: "Generate 2FA codes", link: "/manual/larepass/two-factor-verification"}, + ], + }, + { + text: "Manage knowledge", + link: "/manual/larepass/manage-knowledge", + }, + ], + }, + { + text: "Olares applications", + collapsed: true, + link: "/manual/olares/", + items: [ + { text: "Desktop", link: "/manual/olares/desktop", }, + { text: "Market", link: "/manual/olares/market", }, + { + text: "Files", + collapsed: true, + link: "/manual/olares/files/", + items: [ + { + text: "Basic file operations", + link: "/manual/olares/files/add-edit-download", + }, + { + text: "Sync and share", + link: "/manual/larepass/sync-share", + }, + { + text: "Mount SMB", + link: "/manual/olares/files/mount-SMB", + }, + {text: "Mount cloud storage", + link: "/manual/olares/files/mount-cloud-storage", + }, + ], + }, + { + text: "Vault", + collapsed: true, + link: "/manual/olares/vault/", + items: [ + { + text: "Manage vault items", + link: "/manual/olares/vault/vault-items", + }, + { + text: "Manage shared vault", + link: "/manual/olares/vault/share-vault-items", + }, + { + text: "Autofill", + link: "/manual/larepass/autofill", + }, + { + text: "Generate 2FA codes", + link: "/manual/larepass/two-factor-verification", + }, + ], + }, + { + text: "Wise", + collapsed: true, + link: "/manual/olares/wise/", + items: [ + { + text: "Basic operations", + link: "/manual/olares/wise/basics", + }, + { + text: "Get recommendation engine", + link: "/manual/olares/wise/recommend", + }, + { + text: "Manage your feeds", + link: "/manual/olares/wise/subscribe", + }, + { + text: "Organize your knowledge", + link: "/manual/olares/wise/filter", + }, + ], + }, + { + text: "Control Hub", + collapsed: true, + link: "/manual/olares/controlhub/", + items: [ + { + text: "Navigate Control Hub", + link: "/manual/olares/controlhub/navigate-control-hub", + }, + { + text: "Edit system resource", + link: "/manual/olares/controlhub/edit-resource", + }, + { + text: "View container status", + link: "/manual/olares/controlhub/view-container", + }, + ], + }, + { + text: "Settings", + collapsed: true, + link: "/manual/olares/settings/", + items: [ + { + text: "My Olares", + collapsed: true, + items: [ + {text: "Account and device", link: "/manual/olares/settings/my-olares"}, + {text: "Update system", link: "/manual/olares/settings/update"}, + ], + }, + { + text: "Manage accounts", + collapsed: true, + items: [ + { + text: "Roles and permissions", + link: "/manual/olares/settings/roles-permissions", + }, + { + text: "Create member accounts", + link: "/manual/olares/settings/manage-team", + } + ], + }, + { + text: "Manage applications", + collapsed: true, + items: [ + { + text: "Manage app entrance", + link: "/manual/olares/settings/manage-entrance", + }, + { + text: "Customize app domains", + link: "/manual/olares/settings/custom-app-domain", + }, + ], + }, + { + text: "Manage integrations", + link:"/manual/olares/settings/integrations", + }, + { + text: "Customize appearance", + link:"/manual/olares/settings/language-appearance", + }, + {text: "Manage VPN", link: "/manual/olares/settings/remote-access",}, + { + text: "Configure network", + collapsed: true, + items: [ + { + text: "Change revere proxy", + link: "/manual/olares/settings/change-frp", + }, + { + text: "Set up hosts file", + link:"/manual/olares/settings/set-up-hosts", + }, + ], + }, + {text: "Manage GPU", link: "/manual/olares/settings/gpu-resource",}, + { + text: "Backup and restore", + collapsed: true, + items: [ + {text: "Backup", link: "/manual/olares/settings/backup"}, + {text: "Restore", link: "/manual/olares/settings/restore"}, + ], + }, + {text: "Developer resources", link: "/manual/olares/settings/developer"}, + ] + }, + {text: "Dashboard", link: "/manual/olares/resources-usage"}, + {text: "Profile", link: "/manual/olares/profile"}, + ], + }, + { + text: "Best practices", + link: "/manual/best-practices/", + collapsed: true, + items: [ + { + text: "Set up custom domain", + link: "/manual/best-practices/set-custom-domain", + }, + { + text: "Manage knowledge with Wise", + link: "/manual/best-practices/organize-content", + }, + { + text: "Install a multi-node Olares cluster", + link: "/manual/best-practices/install-olares-multi-node", + }, + ], + }, + { + text: "Concepts", + collapsed: true, + link: "/manual/concepts/", + items: [ + { text: "Architecture", link: "/manual/concepts/architecture" }, + { text: + "Olares ID", + link: "/manual/concepts/olares-id", + collapsed: true, + items: [ + { + text: "Decentralized ID", + link: "/manual/concepts/did", + }, + { + text: "Blockchain Registry", + link: "/manual/concepts/registry", + }, + { + text: "Verifiable Credential", + link: "/manual/concepts/vc", + }, + { + text: "Autonomous Reputation", + link: "/manual/concepts/reputation", + }, + { + text: "Self-Sovereign Network", + link: "/manual/concepts/self-sovereign-network", + }, + { + text: "Identity Wallet", + link: "/manual/concepts/wallet", + }, + ], + }, + { text: "Account", link: "/manual/concepts/account" }, + { text: "Application", link: "/manual/concepts/application" }, + { text: "Network", link: "/manual/concepts/network" }, + { text: "Data", link: "/manual/concepts/data" }, + { text: "Secrets", link: "/manual/concepts/secrets" }, + ], + }, + { text: "Glossary", link: "/manual/glossary" }, + ], + "/space/": [ + { + text: "Olares Space", + link: "/space/", + items: [ + { + text: "Manage accounts", + link: "/space/manage-accounts", + }, + { + text: "Host Olares", + collapsed: true, + items: [ + { + text: "Create Olares", + link: "/space/create-olares", + }, + { + text: "Manage Olares", + link: "/space/manage-olares", + }, + ], + }, + { + text: "Host domains", + collapsed: true, + items: [ + { + text: "Set up a custom domain", + link: "/space/host-domain", + }, + { + text: "Manage a domain", + link: "/space/manage-domain", + }, + ], + }, + { + text: "Back up and restore", + link: "/space/backup-restore", + }, + { text: "Billing", link: "/space/billing" }, + ], + }, + ], + "/use-cases/": [ + { + text: "Tutorials & use cases", + link: "/use-cases/", + items: [ + { + text: "Stable Diffusion", + link: "/use-cases/stable-diffusion", + }, + { + text: "ComfyUI", + link: "/use-cases/comfyui", + collapsed: true, + items: [ + { + text: "Manage ComfyUI", + link: "/use-cases/comfyui-launcher", + }, + { + text: "Use ComfyUI for Krita", + link: "/use-cases/comfyui-for-krita", + }, + ] + }, + { + text: "Ollama", + link: "/use-cases/ollama", + }, + { + text: "Open WebUI", + link: "/use-cases/openwebui", + }, + { + text: "Perplexica", + link: "/use-cases/perplexica", + }, + { + text: "Dify", + link: "/use-cases/dify", + }, + { + text: "Jellyfin", + link: "/use-cases/stream-media", + }, + { + text: "Steam", + link: "/use-cases/stream-game", + }, + { + text: "Redroid", + link: "/use-cases/host-cloud-android", + }, + ], + }, + ], + "/developer/": [ + { + text: "Installation deep-dives", + link: "/developer/install/", + items: [ + { + text: "Installation architecture", + link: "/developer/install/installation-overview", + }, + { + text: "Installation process", + link: "/developer/install/installation-process", + }, + { + text: "Olares Home", + link: "/developer/install/olares-home", + }, + { + text: "Environment variables", + link: "/developer/install/environment-variables", + }, + { + text: "Olares CLI", + link: "/developer/install/cli/olares-cli", + collapsed: true, + items: [ + { text: "gpu", link: "/developer/install/cli/gpu" }, + { text: "osinfo", link: "/developer/install/cli/osinfo" }, + { text: "node", link: "/developer/install/cli/node" }, + { + text: "backups", + link: "/developer/install/cli/backups", + collapsed: true, + items: [ + {text: "download", link: "/developer/install/cli/backups-download"}, + {text: "region", link: "/developer/install/cli/backups-region"}, + {text: "backup", link: "/developer/install/cli/backups-backup"}, + {text: "restore", link: "/developer/install/cli/backups-restore"}, + {text: "snapshots", link: "/developer/install/cli/backups-snapshots"}, + ], + }, + { + text: "change-ip", + link: "/developer/install/cli/change-ip", + }, + { + text: "download", + link: "/developer/install/cli/download", + }, + { text: "info", link: "/developer/install/cli/info" }, + { + text: "install", + link: "/developer/install/cli/install", + }, + { + text: "logs", + link: "/developer/install/cli/logs", + }, + { + text: "precheck", + link: "/developer/install/cli/precheck", + }, + { + text: "prepare", + link: "/developer/install/cli/prepare", + }, + { + text: "release", + link: "/developer/install/cli/release", + }, + { + text: "start", + link: "/developer/install/cli/start", + }, + { + text: "stop", + link: "/developer/install/cli/stop", + }, + { + text: "uninstall", + link: "/developer/install/cli/uninstall", + }, + ], + }, + { + text: "Olares versioning", + link: "/developer/install/versioning", + }, + ], + }, + // { + // text: "Additional installations", + // link: "/developer/install/additional-installations", + // collapsed: true, + // items: [ + // { text: "Linux (via Docker)", link: "/developer/install/linux-via-docker-compose"}, + // { + // text: "macOS", + // collapsed: true, + // items: [ + // { + // text: "Using the script (recommended)", + // link: "/developer/install/mac", + // }, + // { + // text: "Using Docker image", + // link: "/developer/install/mac-via-docker-image", + // }, + // ], + // }, + // { + // text: "Windows (WSL 2)", + // collapsed: true, + // items: [ + // { + // text: "Using the script (recommended)", + // link: "/developer/install/windows", + // }, + // { + // text: "Using Docker image", + // link: "/developer/install/windows-via-docker-image", + // }, + // ], + // }, + // { text: "PVE", link: "/developer/install/pve" }, + // { text: "LXC", link: "/developer/install/lxc" }, + // { text: "Raspberry Pi", link: "/developer/install/raspberry-pi" }, + // ], + // }, + { + text: "Develop Olares app", + link: "/developer/develop/", + items: [ + { + text: "Tutorial", + collapsed: true, + link: "/developer/develop/tutorial/", + items: [ + { + text: "Learn Studio", + link: "/developer/develop/tutorial/studio", + }, + { + text: "Create your first app", + collapsed: true, + link: "/developer/develop/tutorial/note/", + items: [ + { + text: "1. Create app", + link: "/developer/develop/tutorial/note/create", + }, + { + text: "2. Develop backend", + link: "/developer/develop/tutorial/note/backend", + }, + { + text: "3. Develop frontend", + link: "/developer/develop/tutorial/note/frontend", + }, + ], + }, + ], + }, + { + text: "Application package", + collapsed: true, + items: [ + { + text: "Application chart", + link: "/developer/develop/package/chart", + }, + { + text: "OlaresManifest", + link: "/developer/develop/package/manifest", + }, + { + text: "Recommendation", + link: "/developer/develop/package/recommend", + }, + { + text: "Helm extension", + link: "/developer/develop/package/extension", + }, + ], + }, + { + text: "Advanced", + collapsed: true, + items: [ + { + text: "terminus-info", + link: "/developer/develop/advanced/terminus-info", + }, + { + text: "Service provider", + link: "/developer/develop/advanced/provider", + }, + { + text: "AI", + link: "/developer/develop/advanced/ai", + }, + { text: "Cookie", link: "/developer/develop/advanced/cookie" }, + { text: "Database", link: "/developer/develop/advanced/database" }, + { + text: "Account", + link: "/developer/develop/advanced/account", + }, + { + text: "Market", + link: "/developer/develop/advanced/market", + }, + { + text: "Websocket", + link: "/developer/develop/advanced/websocket", + }, + { + text: "File upload", + link: "/developer/develop/advanced/file-upload", + }, + { + text: "Secret", + link: "/developer/develop/advanced/secret", + }, + { + text: "Kubesphere", + link: "/developer/develop/advanced/kubesphere", + }, + ], + }, + + { + text: "Submit application", + collapsed: true, + link: "/developer/develop/submit/", + }, + ], + }, + { + text: "Contribute to Olares", + items: [ + { + text: "Develop system app", + collapsed: true, + items: [ + { + text: "Overview", + link: "/developer/contribute/system-app/overview", + }, + { + text: "Configure deployment", + link: "/developer/contribute/system-app/deployment", + }, + { + text: "Configure permissions", + link: "/developer/contribute/system-app/olares-manifest", + }, + { + text: "Install", + link: "/developer/contribute/system-app/install", + }, + { + text: "Other", + link: "/developer/contribute/system-app/other", + }, + ], + }, + { + text: "Develop protocols", + collapsed: true, + items: [ + { + text: "Contract", + link: "/developer/contribute/olares-id/contract/contract", + collapsed: true, + items: [ + { + text: "Architecture", + link: "/developer/contribute/olares-id/contract/architecture", + }, + { + text: "DID", + collapsed: true, + items: [ + { + text: "Design", + link: "/developer/contribute/olares-id/contract/did/design", + }, + { + text: "Official Taggers", + link: "/developer/contribute/olares-id/contract/did/official-taggers", + }, + { + text: "Release History", + link: "/developer/contribute/olares-id/contract/did/release-history", + }, + { + text: "FAQ", + link: "/developer/contribute/olares-id/contract/did/faq", + }, + ], + }, + { + text: "Reputation", + link: "/developer/contribute/olares-id/contract/contract-reputation", + }, + { + text: "Manage", + collapsed: true, + items: [ + { + text: "Contract", + link: "/developer/contribute/olares-id/contract/manage/contract", + }, + { + text: "SDK", + link: "/developer/contribute/olares-id/contract/manage/sdk", + }, + { + text: "Environment", + link: "/developer/contribute/olares-id/contract/manage/environment", + }, + ], + }, + ], + }, + { + text: "Verifiable Credential", + link: "/developer/contribute/olares-id/verifiable-credential/overview", + collapsed: true, + items: [ + { + text: "Issuer", + link: "/developer/contribute/olares-id/verifiable-credential/issuer", + }, + { + text: "Verifer", + link: "/developer/contribute/olares-id/verifiable-credential/verifer", + }, + { + text: "Olares", + link: "/developer/contribute/olares-id/verifiable-credential/olares", + }, + ], + }, + ], + }, + ], + }, + ], +}; + +export const en = defineConfig({ + lang: "en", + themeConfig: { + //logo: "/icon.png", + socialLinks: [{ icon: "github", link: "https://github.com/beclab/olares" }], + + nav: [ + { text: "Olares", link: "/manual/docs-home" }, + { text: "Olares Space", link: "/space/" }, + { text: "Use Cases", link: "/use-cases/" }, + { text: "Developer Guide", link: "/developer/install/" }, + ], + + sidebar: side, + }, +}); diff --git a/docs/.vitepress/theme/components/FilterableList.vue b/docs/.vitepress/theme/components/FilterableList.vue new file mode 100644 index 000000000..96e2c308d --- /dev/null +++ b/docs/.vitepress/theme/components/FilterableList.vue @@ -0,0 +1,108 @@ + + + + + \ No newline at end of file diff --git a/docs/.vitepress/theme/components/LaunchCard.vue b/docs/.vitepress/theme/components/LaunchCard.vue new file mode 100644 index 000000000..b75990dd5 --- /dev/null +++ b/docs/.vitepress/theme/components/LaunchCard.vue @@ -0,0 +1,90 @@ + + + + + \ No newline at end of file diff --git a/docs/.vitepress/theme/components/Layout.vue b/docs/.vitepress/theme/components/Layout.vue new file mode 100644 index 000000000..3fa945b9b --- /dev/null +++ b/docs/.vitepress/theme/components/Layout.vue @@ -0,0 +1,24 @@ + + + + + + diff --git a/docs/.vitepress/theme/components/OStabs.vue b/docs/.vitepress/theme/components/OStabs.vue new file mode 100644 index 000000000..5dff33e96 --- /dev/null +++ b/docs/.vitepress/theme/components/OStabs.vue @@ -0,0 +1,97 @@ + + + + + diff --git a/docs/.vitepress/theme/components/VersionSwitcher.vue b/docs/.vitepress/theme/components/VersionSwitcher.vue new file mode 100644 index 000000000..cbfaffed2 --- /dev/null +++ b/docs/.vitepress/theme/components/VersionSwitcher.vue @@ -0,0 +1,195 @@ + + + + + + + diff --git a/docs/.vitepress/theme/components/tabs.vue b/docs/.vitepress/theme/components/tabs.vue new file mode 100644 index 000000000..80fbaed9e --- /dev/null +++ b/docs/.vitepress/theme/components/tabs.vue @@ -0,0 +1,122 @@ + + + + + diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts new file mode 100644 index 000000000..7cf7f2af7 --- /dev/null +++ b/docs/.vitepress/theme/index.ts @@ -0,0 +1,139 @@ +// docs/.vitepress/theme/index.ts +import DefaultTheme from "vitepress/theme"; +import "./styles/custom.css"; +import "./styles/index.css"; +import { inBrowser, useRoute, useRouter, useData } from "vitepress"; +import Layout from "./components/Layout.vue"; +import { injectSpeedInsights } from "@vercel/speed-insights"; +import { inject } from "@vercel/analytics"; +import { App } from "vue"; +import Tabs from "./components/tabs.vue"; +import LaunchCard from "./components/LaunchCard.vue"; +import FilterableList from "./components/FilterableList.vue"; +import { onMounted, watch, nextTick, onBeforeMount,computed } from "vue"; +import mediumZoom from "medium-zoom"; +import OSTabs from "./components/OStabs.vue"; +import VersionSwitcher from "./components/VersionSwitcher.vue"; +import _ from "lodash"; + +const LANGUAGE_ZH_PATH = "/zh/"; +const LANGUAGE_ZH_KEY = "zh"; +const LANGUAGE_EN_KEY = "en"; + +const LANGUAGE_LOCAL_KEY = "language"; +let isMenuChange = false; + +export default { + extends: DefaultTheme, + Layout, + enhanceApp({ app }: { app: App }) { + app.component("Tabs", Tabs); + app.component("LaunchCard", LaunchCard); + app.component("FilterableList", FilterableList); + app.component("OSTabs", OSTabs); + app.component("VersionSwitcher", VersionSwitcher); + }, + + setup() { + const route = useRoute(); + const router = useRouter(); + const { lang } = useData(); + + const routerRedirect = () => { + let localLanguage = localStorage.getItem(LANGUAGE_LOCAL_KEY) || 'en'; + + const versions = process.env.VERSIONS!.split(",") ||[]; + versions.push('default'); + + const languages = process.env.LANGUAGES!.split(",") || []; + languages.push('en'); + console.log(versions, languages,localLanguage) + + if(!languages?.includes(localLanguage) ){ + localLanguage = 'en'; + } + + + const currentPath = router.route.path; + + console.log('router.route.path', router.route.path); + for( const l of languages ) { + let localLanguagePath = (l === 'en' ? '' : `/${l}`); + for (const v of versions) { + let localVersionPath = (v === 'default' ? '' : `/${v}`); + const u = `${localVersionPath}${localLanguagePath}`; + console.log('checkPrefix', u); + if (currentPath.startsWith(u)) { + console.log('find localLanguage', localLanguage, l); + if( l !== localLanguage ) { + let targetLanguagePath = (localLanguage === 'en' ? '' : `/${localLanguage}`); + const nextUrl = `${localVersionPath}${targetLanguagePath}${route.path.replace(u, '')}`; + router.go(nextUrl); + } + return; + + } + } + } + }; + + const initZoom = () => { + mediumZoom(".main img", { background: "var(--vp-c-bg)" }); + }; + + const toggleMenuStatus = () => { + const menuDom = document.querySelector(".menu .VPMenu"); + menuDom?.addEventListener("click", (e) => { + const target = e.target as Element; + const isLink = target.closest(".VPMenuLink"); + if (isLink) { + isMenuChange = true; + } + }); + }; + + if (inBrowser) { + routerRedirect(); + } + + onMounted(() => { + toggleMenuStatus(); + inject(); + injectSpeedInsights(); + initZoom(); + + document + .querySelector(".wrapper .container a.title") + ?.setAttribute("href", "https://www.olares.com/"); + + document + .querySelector(".wrapper .container a.title") + ?.setAttribute("target", "_blank"); + }); + + watch( + () => lang.value, + (newValue) => { + localStorage.setItem(LANGUAGE_LOCAL_KEY, newValue); + isMenuChange = false; + } + ); + + watch( + () => route.path, + () => { + nextTick(() => { + initZoom(); + + document + .querySelector(".wrapper .container a.title") + ?.setAttribute("href", "https://www.olares.com/"); + + document + .querySelector(".wrapper .container a.title") + ?.setAttribute("target", "_blank"); + }); + } + ); + }, +}; diff --git a/docs/.vitepress/theme/styles/cta-container.css b/docs/.vitepress/theme/styles/cta-container.css new file mode 100644 index 000000000..a23030237 --- /dev/null +++ b/docs/.vitepress/theme/styles/cta-container.css @@ -0,0 +1,64 @@ +.cta-container { + display: flex; + flex-wrap: wrap; + gap: 1rem; + margin-top: 2rem; +} + +.cta-link { + display: flex; + flex-direction: column; + justify-content: space-between; + flex: 1 1 calc(33.333% - 1rem); + padding: 1rem; + text-decoration: none; + border-radius: 8px; + transition: box-shadow 0.3s ease, transform 0.3s ease; + color: #333; + box-sizing: border-box; +} + +.cta-link:hover { + box-shadow: 0 4px 8px rgba(0, 0, 0, 0.2); + transform: translateY(-2px); +} + +.cta-title { + font-size: 20px; + line-height: 1.4; + letter-spacing: -0.02em; + margin-bottom: 0.75em; + color: #ec5b68; +} + +.cta-description { + margin-bottom: 0; + color: #757575; +} + +@media (max-width: 768px) { + .cta-link { + flex: 1 1 calc(50% - 1rem); + } +} + +@media (max-width: 480px) { + .cta-link { + flex: 1 1 100%; + } +} + +:root.dark { + .cta-link { + background-color: #222; + color: #f5f5f5; + } + + .cta-title { + color: #ff6f61; + } + + .cta-description { + color: #aaa; + } +} diff --git a/docs/.vitepress/theme/styles/cta.css b/docs/.vitepress/theme/styles/cta.css new file mode 100644 index 000000000..e3396e06b --- /dev/null +++ b/docs/.vitepress/theme/styles/cta.css @@ -0,0 +1,71 @@ +.cta { + margin: 2rem 0; + border-radius: 8px; + overflow: hidden; + box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1); + transition: all 0.3s ease; +} + +.cta:hover { + transform: translateY(-2px); + box-shadow: 0 4px 6px rgba(0, 0, 0, 0.15); +} + +.cta a { + display: flex; + align-items: center; + justify-content: space-between; + padding: 1rem 1.5rem; + background-color: #f5f5f5; + color: #333; + text-decoration: none; +} + +.cta a:hover { + color: #333; /* 保持颜色不变 / + text-decoration: none; / 移除可能的下划线 */ +} + +.cta .content { + flex-grow: 1; +} + +.cta h3 { + margin: 0; + font-size: 1rem; + font-weight: 600; +} + +.cta p { + margin: 0.25rem 0 0; + font-size: 0.9rem; + opacity: 0.7; +} + +.cta .arrow { + font-size: 1.5rem; + font-weight: bold; + margin-left: 1rem; + color: #666; +} + +.cta a:hover .arrow { + color: #666; /* 保持箭头颜色不变 */ +} + +:root.dark { + .cta a { + background-color: #222; + color: #f5f5f5; + } + .cta a:hover { + background-color: #333; + color: #fff; + } + .cta .arrow { + color: #ccc; + } + .cta a:hover .arrow { + color: #fff; + } +} diff --git a/docs/.vitepress/theme/styles/custom.css b/docs/.vitepress/theme/styles/custom.css new file mode 100644 index 000000000..4e35d17a7 --- /dev/null +++ b/docs/.vitepress/theme/styles/custom.css @@ -0,0 +1,8 @@ +/* 只影响文档正文里的表格 */ +.vp-doc table td:nth-child(2), +.vp-doc table th:nth-child(2) { + white-space: nowrap; /* 第二列不换行 */ +} + +/* 若想让整张表放宽布局，顺便改一下 ↓ */ +/* .vp-doc table { table-layout: auto; } */ diff --git a/docs/.vitepress/theme/styles/image.css b/docs/.vitepress/theme/styles/image.css new file mode 100644 index 000000000..e56d0aa75 --- /dev/null +++ b/docs/.vitepress/theme/styles/image.css @@ -0,0 +1,8 @@ +img[src*="bordered"] { + display: block; + margin-top: 0.5em; + margin-left: auto; + margin-right: auto; + box-shadow: 0px 8px 15px rgba(0, 0, 0, 0.2), 0px 4px 6px rgba(0, 0, 0, 0.15); + border-radius: 4px; +} \ No newline at end of file diff --git a/docs/.vitepress/theme/styles/index.css b/docs/.vitepress/theme/styles/index.css new file mode 100644 index 000000000..7b7e61532 --- /dev/null +++ b/docs/.vitepress/theme/styles/index.css @@ -0,0 +1,5 @@ +@import "./links.css"; +@import "./cta.css"; +@import "./cta-container.css"; +@import "./image.css"; + diff --git a/docs/.vitepress/theme/styles/links.css b/docs/.vitepress/theme/styles/links.css new file mode 100644 index 000000000..8078cd5c6 --- /dev/null +++ b/docs/.vitepress/theme/styles/links.css @@ -0,0 +1,8 @@ +:root { + --vp-c-brand: #646cff; + --vp-c-brand-light: #747bff; +} + +.vp-doc a { + text-decoration: none; +} diff --git a/docs/.vitepress/zh.ts b/docs/.vitepress/zh.ts new file mode 100644 index 000000000..fd6f2373e --- /dev/null +++ b/docs/.vitepress/zh.ts @@ -0,0 +1,826 @@ +import { defineConfig, type DefaultTheme } from "vitepress"; + +const side = { + "/zh/manual/": [ + { + text: "文档站", + link: "/zh/manual/docs-home", + items: [ + // { text: "应用场景", link: "/zh/manual/why-olares" }, + //{ text: "功能对比", link: "/zh/manual/feature-overview" }, + { text: "系统架构", link: "/zh/manual/system-architecture" }, + { text: "比较 Olares 和 NAS", link: "/zh/manual/olares-vs-nas" }, + { + text: "帮助与支持", + collapsed: true, + items: [ + { text: "常见问题", link: "/zh/manual/help/faqs" }, + { + text: "技术支持", + link: "/zh/manual/help/request-technical-support", + }, + // { + // text: "Troubleshooting Guide", + // link: "/zh/manual/help/troubleshooting-guide", + // }, + ], + }, + ], + }, + { + text: "快速开始", + collapsed: false, + link: "/zh/manual/get-started/", + items: [ + // { text: "Quick start", link: "/zh/manual/get-started/quick-start" }, + { + text: "创建 Olares ID", + link: "/zh/manual/get-started/create-olares-id", + }, + { + text: "安装激活", + link: "/zh/manual/get-started/install-olares", + }, + { + text: "备份助记词", + link: "/zh/manual/larepass/back-up-mnemonics", + }, + { + text: "探索", + link: "/zh/manual/get-started/next-steps", + }, + ], + }, + { + text: "LarePass", + link: "/zh/manual/larepass/", + collapsed: true, + items: [ + { + text: "管理账户", + collapsed: true, + items: [ + {text: "创建账户", link:"/zh/manual/larepass/create-account"}, + {text: "备份助记词", link: "/zh/manual/larepass/back-up-mnemonics"}, + {text: "管理集成", link:"/zh/manual/larepass/integrations"}, + ], + }, + {text: "管理专用网络", link:"/zh/manual/larepass/private-network"}, + { + text: "管理设备", + collapsed: true, + items: [ + {text: "激活 Olares", link:"/zh/manual/larepass/activate-olares"}, + {text: "管理 Olares", link:"/zh/manual/larepass/manage-olares"}, + ], + }, + { + text: "管理文件", + collapsed: true, + items: [ + {text: "常用文件操作", link:"/zh/manual/larepass/manage-files"}, + {text: "同步与共享", link:"/zh/manual/larepass/sync-share"} + ] + }, + { + text: "管理密码", + collapsed: true, + items: [ + {text: "自动填充", link: "/zh/manual/larepass/autofill"}, + {text: "双重验证", link: "/zh/manual/larepass/two-factor-verification"}, + ], + }, + { + text: "管理内容", + link: "/zh/manual/larepass/manage-knowledge", + }, + ], + }, + { + "text": "Olares 应用", + "collapsed": true, + "link": "/zh/manual/olares/", + "items": [ + { "text": "桌面", "link": "/zh/manual/olares/desktop" }, + { "text": "应用市场", "link": "/zh/manual/olares/market" }, + { + "text": "文件管理器", + "collapsed": true, + "link": "/zh/manual/olares/files/", + "items": [ + { + "text": "基本文件操作", + "link": "/zh/manual/olares/files/add-edit-download" + }, + { + "text": "同步与共享", + "link": "/zh/manual/larepass/sync-share" + }, + { + "text": "挂载 SMB", + "link": "/zh/manual/olares/files/mount-SMB" + }, + { + "text": "挂载云存储", + "link": "/zh/manual/olares/files/mount-cloud-storage" + } + ] + }, + { + "text": "Vault", + "collapsed": true, + "link": "/zh/manual/olares/vault/", + "items": [ + { + "text": "管理 Vault 项目", + "link": "/zh/manual/olares/vault/vault-items" + }, + { + "text": "管理共享 Vault", + "link": "/zh/manual/olares/vault/share-vault-items" + }, + { + "text": "自动填充", + "link": "/zh/manual/larepass/autofill" + }, + { + "text": "双因素验证", + "link": "/zh/manual/larepass/two-factor-verification" + } + ] + }, + { + "text": "Wise", + "collapsed": true, + "link": "/zh/manual/olares/wise/", + "items": [ + { + "text": "基本操作", + "link": "/zh/manual/olares/wise/basics" + }, + { + "text": "获取推荐引擎", + "link": "/zh/manual/olares/wise/recommend" + }, + { + "text": "管理订阅", + "link": "/zh/manual/olares/wise/subscribe" + }, + { + "text": "整理知识", + "link": "/zh/manual/olares/wise/filter" + } + ] + }, + { + "text": "控制面板", + "collapsed": true, + "link": "/zh/manual/olares/controlhub/", + "items": [ + { + "text": "熟悉控制面板", + "link": "/zh/manual/olares/controlhub/navigate-control-hub" + }, + { + "text": "编辑系统资源", + "link": "/zh/manual/olares/controlhub/edit-resource" + }, + { + "text": "查看容器状态", + "link": "/zh/manual/olares/controlhub/view-container" + }, + ], + }, + { + "text": "设置", + "collapsed": true, + "link": "/zh/manual/olares/settings/", + "items": [ + { + "text": "我的 Olares", + "collapsed": true, + "items": [ + {text: "账户与设备", link: "/zh/manual/olares/settings/my-olares"}, + {text: "更新系统", link: "/zh/manual/olares/settings/update"}, + ], + }, + { + "text": "管理账户", + "collapsed": true, + "items": [ + { + "text": "角色与权限", + "link": "/zh/manual/olares/settings/roles-permissions", + }, + { + "text": "创建成员账户", + "link": "/zh/manual/olares/settings/manage-team", + } + ], + }, + { + "text": "管理应用", + "collapsed": true, + "items": [ + { + "text": "管理应用入口", + "link": "/zh/manual/olares/settings/manage-entrance", + }, + { + "text": "自定义应用域名", + "link": "/zh/manual/olares/settings/custom-app-domain", + }, + ], + }, + { + "text": "管理集成", + "link":"/zh/manual/olares/settings/integrations", + }, + { + "text": "自定义外观", + "link":"/zh/manual/olares/settings/language-appearance", + }, + {text: "管理 VPN", link: "/zh/manual/olares/settings/remote-access",}, + { + "text": "配置网络", + "collapsed": true, + "items": [ + { + "text": "更改反向代理", + "link": "/zh/manual/olares/settings/change-frp", + }, + { + "text": "设置 hosts 文件", + "link":"/zh/manual/olares/settings/set-up-hosts", + }, + ], + }, + {text: "管理 GPU", link: "/zh/manual/olares/settings/gpu-resource",}, + { + "text": "备份与恢复", + "collapsed": true, + "items": [ + {text: "备份", link: "/zh/manual/olares/settings/backup"}, + {text: "恢复", link: "/zh/manual/olares/settings/restore"}, + ], + }, + {text: "开发者资源", link: "/zh/manual/olares/settings/developer"}, + ] + }, + { "text": "仪表盘", "link": "/zh/manual/olares/resources-usage" }, + { "text": "Profile", "link": "/zh/manual/olares/profile" } + ] + }, + { + text: "Olares 进阶", + collapsed: true, + link: "/zh/manual/best-practices/", + items: [ + { + text: "设置自定义域名", + link: "/zh/manual/best-practices/set-custom-domain", + }, + { + text: "使用 Wise 管理知识", + link: "/zh/manual/best-practices/organize-content", + }, + { + text: "安装多节点", + link: "/zh/manual/best-practices/install-olares-multi-node", + }, + { + text: "设置 SMTP", + link: "/zh/manual/best-practices/set-up-SMTP-service", + }, + ], + }, + { + text: "概念", + collapsed: true, + link: "/zh/manual/concepts/", + items: [ + { text: "架构", link: "/zh/manual/concepts/architecture" }, + { text: "Olares ID", + link: "/zh/manual/concepts/olares-id", + collapsed: true, + items: [ + { + text: "去中心化标识符", + link: "/zh/manual//concepts/did", + }, + { + text: "DID Registry", + link: "/zh/manual//concepts/registry", + }, + { + text: "可验证凭证", + link: "/zh/manual//concepts/vc", + }, + { + text: "自治声誉", + link: "/zh/manual//concepts/reputation", + }, + { + text: "主权网络", + link: "/zh/manual//concepts/self-sovereign-network", + }, + { + text: "身份钱包", + link: "/zh/manual/concepts/wallet", + }, + ], + + }, + { text: "账户", link: "/zh/manual/concepts/account" }, + { text: "应用", link: "/zh/manual/concepts/application" }, + { text: "网络", link: "/zh/manual/concepts/network" }, + { text: "数据", link: "/zh/manual/concepts/data" }, + { text: "密钥", link: "/zh/manual/concepts/secrets" }, + ], + }, + { text: "术语", link: "/zh/manual/glossary" }, + ], + "/zh/space/": [ + { + text: "Olares Space", + link: "/zh/space/", + collapsed: true, + items: [ + { + text: "管理账号", + link: "/zh/space/manage-accounts", + }, + { + text: "托管 Olares", + collapsed: true, + items: [ + { + text: "创建 Olares", + link: "/zh/space/create-olares", + }, + { + text: "管理 Olares", + link: "/zh/space/manage-olares", + }, + ], + }, + { + text: "托管域名", + collapsed: true, + items: [ + { + text: "设置自定义域名", + link: "/zh/space/host-domain", + }, + { + text: "管理域名", + link: "/zh/space/manage-domain", + }, + ], + }, + { + text: "备份与恢复", + link: "/zh/space/backup-restore", + }, + { text: "计费", link: "/zh/space/billing" }, + ], + }, + ], + "/zh/use-cases/": [ + { + text: "Tutorials & use cases", + link: "/zh/use-cases/", + items: [ + { + text: "Stable Diffusion", + link: "/zh/use-cases/stable-diffusion", + }, + { + text: "ComfyUI", + link: "/zh/use-cases/comfyui", + collapsed: true, + items: [ + { + text: "Manage ComfyUI", + link: "/zh/use-cases/comfyui-launcher", + }, + { + text: "Use ComfyUI for Krita", + link: "/zh/use-cases/comfyui-for-krita", + }, + ] + }, + { + text: "Ollama", + link: "/zh/use-cases/ollama", + }, + { + text: "Open WebUI", + link: "/zh/use-cases/openwebui", + }, + { + text: "Perplexica", + link: "/zh/use-cases/perplexica", + }, + { + text: "Dify", + link: "/zh/use-cases/dify", + }, + { + text: "Jellyfin", + link: "/zh/use-cases/stream-media", + }, + { + text: "Steam", + link: "/zh/use-cases/stream-game", + }, + { + text: "Redroid", + link: "/zh/use-cases/host-cloud-android", + }, + ], + }, + ], + "/zh/developer/": [ + { + text: "Olares 安装详解", + link: "/zh/developer/install/", + items: [ + { + text: "安装概述", + link: "/zh/developer/install/installation-overview", + }, + { + text: "安装流程", + link: "/zh/developer/install/installation-process", + }, + { + text: "Olares Home", + link: "/zh/developer/install/olares-home", + }, + { + text: "环境变量", + link: "/zh/developer/install/environment-variables", + }, + { + text: "Olares CLI", + collapsed: true, + link: "/zh/developer/install/cli/olares-cli", + items: [ + { text: "gpu", link: "/zh/developer/install/cli/gpu" }, + { text: "osinfo", link: "/zh/developer/install/cli/osinfo" }, + { text: "node", link: "/zh/developer/install/cli/node" }, + { + text: "backups", + link: "/zh/developer/install/cli/backups", + collapsed: true, + items: [ + {text: "download", link: "/zh/developer/install/cli/backups-download"}, + {text: "region", link: "/zh/developer/install/cli/backups-region"}, + {text: "backup", link: "/zh/developer/install/cli/backups-backup"}, + {text: "restore", link: "/zh/developer/install/cli/backups-restore"}, + {text: "snapshots", link: "/zh/developer/install/cli/backups-snapshots"}, + ], + }, + { + text: "change-ip", + link: "/zh/developer/install/cli/change-ip", + }, + { + text: "download", + link: "/zh/developer/install/cli/download", + }, + { text: "info", link: "/zh/developer/install/cli/info" }, + { + text: "install", + link: "/zh/developer/install/cli/install", + }, + { + text: "logs", + link: "/zh/developer/install/cli/logs", + }, + { + text: "precheck", + link: "/zh/developer/install/cli/precheck", + }, + { + text: "prepare", + link: "/zh/developer/install/cli/prepare", + }, + { + text: "release", + link: "/zh/developer/install/cli/release", + }, + { + text: "start", + link: "/zh/developer/install/cli/start", + }, + { + text: "stop", + link: "/zh/developer/install/cli/stop", + }, + { + text: "uninstall", + link: "/zh/developer/install/cli/uninstall", + }, + ], + }, + { + text: "版本说明", + link: "/zh/developer/install/versioning", + }, + // { + // text: "其他安装方式", + // link: "/zh/developer/install/additional-installations", + // collapsed: true, + // items: [ + // { text: "Linux（Docker 镜像）", link: "/zh/developer/install/linux-via-docker-compose" }, + // { + // text: "macOS", + // collapsed: true, + // items: [ + // { + // text: "使用脚本（推荐）", + // link: "/zh/developer/install/mac", + // }, + // { + // text: "使用 Docker 镜像", + // link: "/zh/developer/install/mac-via-docker-image", + // }, + // ], + // }, + // { + // text: "Windows (WSL 2)", + // collapsed: true, + // items: [ + // { + // text: "使用脚本（推荐）", + // link: "/zh/developer/install/windows", + // }, + // { + // text: "使用 Docker 镜像", + // link: "/zh/developer/install/windows-via-docker-image", + // }, + // ], + // }, + // { text: "PVE", link: "/zh/developer/install/pve" }, + // { text: "LXC", link: "/zh/developer/install/lxc" }, + // { text: "树莓派", link: "/zh/developer/install/raspberry-pi" }, + // ], + // }, + ], + }, + { + text: "开发 Olares 应用", + link: "/zh/developer/develop/", + items: [ + { + text: "教程", + collapsed: true, + link: "/zh/developer/develop/tutorial/", + items: [ + { + text: "了解 Studio", + link: "/zh/developer/develop/tutorial/studio", + }, + { + text: "创建首个应用", + collapsed: true, + link: "/zh/developer/develop/tutorial/note/", + items: [ + { + text: "1. 创建应用", + link: "/zh/developer/develop/tutorial/note/create", + }, + { + text: "2. 开发后端", + link: "/zh/developer/develop/tutorial/note/backend", + }, + { + text: "3. 开发前端", + link: "/zh/developer/develop/tutorial/note/frontend", + }, + ], + }, + ], + }, + { + text: "应用包管理", + collapsed: true, + items: [ + { + text: "应用 Chart 包", + link: "/zh/developer/develop/package/chart", + }, + { + text: "OlaresManifest", + link: "/zh/developer/develop/package/manifest", + }, + { + text: "推荐算法", + link: "/zh/developer/develop/package/recommend", + }, + { + text: "Helm 扩展", + link: "/zh/developer/develop/package/extension", + }, + ], + }, + { + text: "进阶", + collapsed: true, + items: [ + { + text: "terminus-info", + link: "/zh/developer/develop/advanced/terminus-info", + }, + { + text: "Service Provider", + link: "/zh/developer/develop/advanced/provider", + }, + { + text: "AI", + link: "/zh/developer/develop/advanced/ai", + }, + { text: "Cookie", link: "/zh/developer/develop/advanced/cookie" }, + { text: "数据库", link: "/zh/developer/develop/advanced/database" }, + { + text: "账户", + link: "/zh/developer/develop/advanced/account", + }, + { + text: "应用市场", + link: "/zh/developer/develop/advanced/market", + }, + // { + // text: "Analytic", + // link: "/zh/developer/develop/advanced/analytic", + // }, + { + text: "Websocket", + link: "/zh/developer/develop/advanced/websocket", + }, + { + text: "文件上传", + link: "/zh/developer/develop/advanced/file-upload", + }, + // { + // text: "Rss", + // link: "/zh/developer/develop/advanced/rss", + // }, + { + text: "密钥", + link: "/zh/developer/develop/advanced/secret", + }, + // { + // text: "Notification", + // link: "/zh/developer/develop/advanced/notification", + // }, + // { + // text: "Frontend", + // link: "/zh/developer/develop/advanced/frontend", + // }, + { + text: "Kubesphere", + link: "/zh/developer/develop/advanced/kubesphere", + }, + ], + }, + + { + text: "提交应用", + collapsed: true, + link: "/zh/developer/develop/submit/", + }, + ], + }, + { + text: "参与贡献", + items: [ + { + text: "开发系统应用", + collapsed: true, + items: [ + { + text: "概述", + link: "/zh/developer/contribute/system-app/overview", + }, + { + text: "应用部署配置", + link: "/zh/developer/contribute/system-app/deployment", + }, + { + text: "Olares 权限配置", + link: "/zh/developer/contribute/system-app/olares-manifest", + }, + { + text: "安装", + link: "/zh/developer/contribute/system-app/install", + }, + { + text: "其他", + link: "/zh/developer/contribute/system-app/other", + }, + ], + }, + { + text: "开发协议", + collapsed: true, + items: [ + { + text: "合约", + link: "/zh/developer/contribute/olares-id/contract/contract", + collapsed: true, + items: [ + { + text: "架构", + link: "/zh/developer/contribute/olares-id/contract/architecture", + }, + { + text: "DID", + collapsed: true, + items: [ + { + text: "设计", + link: "/zh/developer/contribute/olares-id/contract/did/design", + }, + { + text: "官方 Tagger", + link: "/zh/developer/contribute/olares-id/contract/did/official-taggers", + }, + { + text: "发布历史", + link: "/zh/developer/contribute/olares-id/contract/did/release-history", + }, + { + text: "FAQ", + link: "/zh/developer/contribute/olares-id/contract/did/faq", + }, + ], + }, + { + text: "声誉", + link: "/zh/developer/contribute/olares-id/contract/contract-reputation", + }, + { + text: "管理", + collapsed: true, + items: [ + { + text: "合约", + link: "/zh/developer/contribute/olares-id/contract/manage/contract", + }, + { + text: "SDK", + link: "/zh/developer/contribute/olares-id/contract/manage/sdk", + }, + { + text: "环境", + link: "/zh/developer/contribute/olares-id/contract/manage/environment", + }, + ], + }, + ], + }, + { + text: "可验证凭证（VC）", + link: "/zh/developer/contribute/olares-id/verifiable-credential/overview", + collapsed: true, + items: [ + { + text: "发行方", + link: "/zh/developer/contribute/olares-id/verifiable-credential/issuer", + }, + { + text: "验证方", + link: "/zh/developer/contribute/olares-id/verifiable-credential/verifer", + }, + { + text: "Olares 案例", + link: "/zh/developer/contribute/olares-id/verifiable-credential/olares", + }, + ], + }, + ], + }, + ], + }, + ], +}; + +export const zh = defineConfig({ + lang: "zh", + themeConfig: { + //logo: "/icon.png", + socialLinks: [{ icon: "github", link: "https://github.com/beclab/olares" }], + + nav: [ + { text: "Olares", link: "zh/manual/docs-home" }, + { text: "Olares Space", link: "/zh/space/" }, + { text: "应用示例", link: "/zh/use-cases/" }, + { text: "开发者文档", link: "/zh/developer/install/" }, + ], + + sidebar: side, + }, +}); diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 000000000..261eeb9e9 --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/docs/README.md b/docs/README.md index 056a08ebd..b753e192e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,3 +1,10 @@ -# Olares Doc +# Olares Docs -https://github.com/beclab/docs \ No newline at end of file +## Run + +```shell +npm install +npm run dev +``` + +Open Browser at `http://localhost:5173/` diff --git a/docs/code-snippets/docker-compose-GPU.yaml b/docs/code-snippets/docker-compose-GPU.yaml new file mode 100644 index 000000000..cc37a9130 --- /dev/null +++ b/docs/code-snippets/docker-compose-GPU.yaml @@ -0,0 +1,31 @@ +services: + olares: + image: beclab/olares:${VERSION} + privileged: true + volumes: + - oic-data:/var + ports: + - "80:80" + - "443:443" + - "30180:30180" + - "18088:18088" + - "41641:41641/udp" + environment: + - HOST_IP=${HOST_IP} + deploy: + resources: + reservations: + devices: + - driver: nvidia + count: 1 + capabilities: [gpu] + + olaresd-proxy: + image: beclab/olaresd:proxy-v0.1.0 + network_mode: host + depends_on: + olares: + condition: service_started + +volumes: + oic-data: \ No newline at end of file diff --git a/docs/code-snippets/docker-compose.yaml b/docs/code-snippets/docker-compose.yaml new file mode 100644 index 000000000..9c6332685 --- /dev/null +++ b/docs/code-snippets/docker-compose.yaml @@ -0,0 +1,24 @@ +services: + olares: + image: beclab/olares:${VERSION} + privileged: true + volumes: + - oic-data:/var + ports: + - "80:80" + - "443:443" + - "30180:30180" + - "18088:18088" + - "41641:41641/udp" + environment: + - HOST_IP=${HOST_IP} + + olaresd-proxy: + image: beclab/olaresd:proxy-v0.1.0 + network_mode: host + depends_on: + olares: + condition: service_started + +volumes: + oic-data: diff --git a/docs/code-snippets/docker-daemon.json b/docs/code-snippets/docker-daemon.json new file mode 100644 index 000000000..3e299d85a --- /dev/null +++ b/docs/code-snippets/docker-daemon.json @@ -0,0 +1,9 @@ +{ + "registry-mirrors": [ + "https://mirrors.joinolares.cn" + ], + + "features": { + "containerd-snapshotter": false + } +} \ No newline at end of file diff --git a/docs/compress_images.sh b/docs/compress_images.sh new file mode 100644 index 000000000..3c374150e --- /dev/null +++ b/docs/compress_images.sh @@ -0,0 +1,52 @@ +#!/bin/bash + +# Check if pngquant and jpegoptim are installed +if ! command -v pngquant &> /dev/null; then + echo "pngquant is not installed. Please install it first." + exit 1 +fi + +if ! command -v jpegoptim &> /dev/null; then + echo "jpegoptim is not installed. Please install it first." + exit 1 +fi + +# Create base compress directory if it doesn't exist +mkdir -p compress + +# Function to process a single file +process_file() { + local source_file="$1" + # Remove 'public/' prefix and prepend 'compress/' + local target_file="compress/${source_file#public/}" + # Get the directory path of the target file + local target_dir="$(dirname "$target_file")" + + # Create target directory if it doesn't exist + mkdir -p "$target_dir" + + # Copy file first to preserve original + cp "$source_file" "$target_file" + + # Process based on file extension + local ext=$(echo "${source_file##*.}" | tr '[:upper:]' '[:lower:]') + + # Process based on file extension + case "$ext" in + png) + echo "Compressing PNG: $source_file" + pngquant --quality=90-95 --skip-if-larger --force --output "$target_file" "$target_file" + ;; + jpg|jpeg) + echo "Compressing JPEG: $source_file" + jpegoptim --max=95 --preserve --strip-none "$target_file" + ;; + esac +} + +# Find and process all PNG and JPEG files +find public -type f \( -iname "*.png" -o -iname "*.jpg" -o -iname "*.jpeg" -o -iname "*.svg" \) | while read -r file; do + process_file "$file" +done + +echo "Image compression completed. Compressed images are in the 'compress' directory." \ No newline at end of file diff --git a/docs/developer/contribute/olares-id/contract/architecture.md b/docs/developer/contribute/olares-id/contract/architecture.md new file mode 100644 index 000000000..0d22219cc --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/architecture.md @@ -0,0 +1,121 @@ +--- +outline: [2, 4] +--- + +# TerminusDID Contract System + +## Architecture + +The TerminusDID Contract System is divided into two parts: DID Management and Tag Management. In addition to the core functions for Tag Management, we also implemented an official tagger and reputation system. + +```mermaid +graph TB + + RootTagger{RootTagger} + + RSAPubKey[/RSAPubKey/] + DNSARecord[/DNSARecord/] + AuthAddress[/AuthAddress/] + otherTag[/.../] + + + + + TerminusDID{TerminusDID} + Reputations[/Reputations\] + XXXReputation{...} + AppMarketReputation{AppMarketReputation} + Tag[[Tag]] + Tagger([Tagger]) + + + DID[DID] + Domain((Domain)) + com((com)) + net((net)) + io((io)) + + TerminusDID--->DID + TerminusDID--->Tag + Tag--->Tagger + + Tagger-.-RootTagger + Tagger-.-AppMarketReputation + Tagger-.-XXXReputation + + + Domain-.->Tag + + + subgraph ide4 [Tag] + + subgraph ide1 [OfficialTag] + RootTagger--->RSAPubKey + RootTagger--->DNSARecord + RootTagger--->AuthAddress + RootTagger--->otherTag + end + + subgraph ide2 [Reputations] + Reputations-.->AppMarketReputation + Reputations-.->XXXReputation + end + + end + + subgraph ide3 [DID] + DID-.-Domain + Domain--->com + Domain--->net + Domain--->io + end + +``` + +Refer [here](./contract.md) for the usage of DID/Tag Management, [here](././did/design.md) for design details of the TerminusDID contract, [here](./contract-reputation.md) for recommended implementations and examples of the reputation system. + +## Design Details + +### Multicall + +Considering the complexity and the uncertainty of usage scenarios of our contracts, we add built-in multicall function to simplify on-chain interaction. You can access multiple interfaces in one transaction without external helper contracts. + +Considering the complexity and uncertainty of usage scenarios of our contracts, we have added a built-in multicall function to simplify on-chain interactions. You can access multiple interfaces in one transaction without external contracts. + + +### EIP-7201 + +We follow EIP-7201 for contract data storage, which makes it easier and safer for contract upgrade and also facilitates granular control of data. + +### Validation of Olares ID + +Olares ID is submitted as a `string` type during registration. Although it is split by `.` for level separation, this cannot guarantee its correctness and readability. We implemented additional validation in contract code to ensure the submitted names are UTF-8-encoded readable strings. + +### Field Names of Structs in Tags + +For gas efficiency, if there are structs in a tag type, their field names are published on-chain using Ethereum events without contract storage. The events will record the block height at which the tag type is defined. Use the block height, contract address, event signature and Bloom filters to get the desired event precisely. + +### Inline Assembly + +We use slice types based on inline assembly to parse and traverse Olares ID levels, which can prevent copying substrings and reduce gas. + +## Appendix - Requirements + +### DID + +- on-chain [DID](https://www.w3.org/TR/did-core/) management (prefer EVM-compatible chains) +- recording IPv4/IPv6, avatar, RSA public key etc. for DIDs +- extending stored data for possible new needs in the future + +### Olares ID + +- distinguishing between two kinds of DIDs for Olares ID: Organization or Individual +- derived DID management privilege for parent Organization + +### Reputation + +DIDs with another kind called Entity to represent real-world objects (e.g. app versions for App Market Reputation and complaints for Otmoic Reputation) + +:::tip Tips +We hope to design a decentralized credit system based on DID contracts. At first we imagined a general system adaptable to various scenarios, but with its gradually implementation we found this large and comprehensive system to bring much unnecessary resource consumption and reduce flexibility in different scenarios. So we changed the direction: we present a Reputation system for abstraction and necessary components and provide some recommended implementations. Users can assembly and customize the implementation to satisfy their own scenarios. +::: diff --git a/docs/developer/contribute/olares-id/contract/contract-reputation.md b/docs/developer/contribute/olares-id/contract/contract-reputation.md new file mode 100644 index 000000000..29b6114f4 --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/contract-reputation.md @@ -0,0 +1,98 @@ +# Reputation + +#### Extra requirements: Abstract Reputation System + +:::info Required features + +- identifiers that map to real-world objects + All credit systems are based on some specific scenarios, e.g. reviews for an app or complaints for a merchant. This inevitably needs us to build unique on-chain identifiers for some real-world or abstract objects. + +- authentication + The most core function of the credit system is reviewing and reviewer authentication is one of its prerequisites. + +- storage of necessary information + After user reviewing, we may need to record the comments or calculate some weighted statistical data. + +- recording of history and updating + Under some circumstances, we may need to record the behavior of reviewing and allow updating existing reviews in the future. + ::: + +The corresponding solution for each requirement is provided in this chapter. + +## Objects to be Reviewed + +For the objects to be reviewed, the following two situations may occur: + +- it's a merchant or a single person + In this case the object must have a DID of kind Individual, so we can operate the object directly without creating other DIDs. +- it's a real-world object or abstract concept + In this case we need to first create a DID of kind Entity for this object and then operate on it. + +## Authentication + +There are two solutions for authentication: + +- Use the owner of the DID to submit tx and let the tagger call interfaces of the Terminus DID contract for authentication. +- Use the owner of the DID to sign a customized EIP-712 message and use a forwarder to send tx on-chain. The tagger will use the message signer for authentication. + +> [!NOTE] Tips +> We recommend the second solution as the transaction fee is paid by forwarders instead of reviewers. + +## Storage of Necessary Information + +For DIDs of kind Entity, we define tags of this DID itself and write necessary data to them. For DIDs of kind Individual, we abstract the scenario as a DID of kind Entity and write to its tags. + +## Recording of History and Updating + +We can follow the advice in the above section and store data in tags of Entity. But on-chain querying is not required in some scenarios, where on-chain storage is a waste. For those cases we recommend to use Ethereum events for recording and customize the detailed implementation in taggers. + +## Example - OtmoicReputation + +:::info + +```mermaid + flowchart LR + + otmoic{{OtmoicReputation}} + did{{TerminusDID}} + complaints[/tag-complaints/] + otmoicdid((otmoic.reputation)) + + otmoic-- Authentication -->did + did-.->otmoicdid + otmoicdid-.-complaints + otmoic-- read/write -->complaints +``` + +The Otmoic Reputation contract uses EIP-712 signature of DID owners for authentication and stores the `bidid` of the complained bid in the `complaints` tag of Entity `otmoic.reputation`. +::: + +## Example - TerminusAppMarketReputation + +:::info + +```mermaid + flowchart TD + + app((app.myterminus.com)) + appname((appname.app.myterminus.com)) + version1((version1.appname.app.myterminus.com)) + version2((version2.appname.app.myterminus.com)) + reputation{{TerminusAppMarketReputation}} + ratings[/tag-ratings/] + version1ratings[/version1-tag-ratings/] + event[[event]] + + app-->appname + appname-->version1 + appname-->version2 + app-.->ratings + ratings-.-version1ratings + version1-.-version1ratings + reputation-.- read/write -.->version1ratings + reputation-.->event + +``` + +The Olares App Market Reputation contract also uses EIP-712 signature of DID owners for authentication. Rating data of the contract is stored in the `ratings` tag of Entity `..app.myterminus.com`, and comment data is published in the form of Ethereum events instead of storing on-chain. +::: diff --git a/docs/developer/contribute/olares-id/contract/contract.md b/docs/developer/contribute/olares-id/contract/contract.md new file mode 100644 index 000000000..4b6788d28 --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/contract.md @@ -0,0 +1,229 @@ +--- +outline: [1, 5] +--- + +# Smart Contract + +Snowinning Protocol's smart contract has two parts. + +- [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol) contract plays a crucial role as the [DID Registry](/manual/concepts/registry.md). Learn more in [the contract](https://optimistic.etherscan.io/address/0x5da4fa8e567d86e52ef8da860de1be8f54cae97d). +- Third-party protocols that extend the reputation system based on [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol). Currently, the following reputation protocols are in place: + - [Otmoic Trader Reputation](https://github.com/otmoic/reputation-contract-evm/blob/main/contracts/Reputation.sol). Learn more in [the contract](https://optimistic.etherscan.io/address/0x3179CE5fAB68C0286Da85f3d61BcE7116815e799). + - [Application Reputation](https://github.com/beclab/terminusdid-contract-system/blob/main/src/taggers/TerminusAppMarketReputation.sol). Learn more in [the contract](https://optimistic.etherscan.io/address/0x08065353D266121938B93D4B1071Bb52CD0C0EE4). + +![alt text](/images/developer/contribute/smart-contract.jpg) + +- The [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol) contract plays a crucial role, and it serves as the [DID Registry](/manual/concepts/registry.md). View [the contract](https://optimistic.etherscan.io/address/0x5da4fa8e567d86e52ef8da860de1be8f54cae97d). +- Third-party protocols can extend the reputation based on [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol). Currently, the following reputation protocols are in place: + - [Otmoic Trader Reputation](https://github.com/otmoic/reputation-contract-evm/blob/main/contracts/Reputation.sol). View [the contract](https://optimistic.etherscan.io/address/0xE924F7f68D1dcd004720e107F62c6303aF271ed3). + - [Application Reputation](https://github.com/beclab/terminusdid-contract-system/blob/main/src/taggers/TerminusAppMarketReputation.sol). View [the contract](https://optimistic.etherscan.io/address/0x08065353D266121938B93D4B1071Bb52CD0C0EE4). + + + +# TerminusDID + +The TerminusDID contract manages a hierarchical structure derived from [Domain](/manual/concepts/olares-id.md#domain-types. + +![alt text](/images/developer/contribute/smart-contract-tree.jpg) + +## Node + +Each node possesses several default attributes. + +| Attribute | Description | +| -------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | Specifies the [Domain Name](/manual/concepts/olares-id.md#domain-types). Certain Domain Names can interchange with Terminus Names | +| id | Each node is also a NFT, adhering to the **ERC-721** standard. Its id serves as the unique identifier for this NFT, computed through `keccak256(name)` | +| did,owner | The `owner` and `did` of the node, derived from the same mnemonic words. Further details on this can be found [here](/manual/concepts/did.md).
. Additionally, storing owner is advantageous because it complies with the **BIP44** specification, facilitating gas-efficient signature verification within EVM contracts. Each node is affiliated with an `owner`, who holds the authority to modify node details. | +| note | Currently, there are three types: Individual, Organization, and Entity | +| allowSubdomain | Indicates whether it is a leaf node. If False, the node cannot spawn further nodes. | + +The following is an illustrative example that specifies the default attributes of a node: + +```json +{ + "id": "0xbf90de759829bfa3d2b10e4c4a7101e3b116f70b9a5431951ff9d83a4c8e3ceb", + "name": "olivia.myterminus.com", + "did": "did:key:z6MkuhT5kYegHaJxirMaHxuqzJhGZk5r32Ct5nYVRQWpN31q", + "note": "Individual", + "owner": "0x1404C95b2Cb2E46E03650bc02f83364A92f8DA9D", + "allowSubdomain": true +} +``` + +## Owner + +Ownership of different nodes is as follows: + +- **System**
+ Abstract nodes such as `root`, `com`, `io` belong to the Terminus team. + +- **Individual**
+ `myterminus.com` belongs to the [Individual Domain](/manual/concepts/olares-id.md#domain-types), owned by the Terminus team. + `alice.myterminus.com` and `bob.myterminus.com` belong to individual Terminus Names, and are owned by the respective users. + +- **Organization**
+ `org1.com` and `org.io` belong to the [Organization Domain](/manual/concepts/olares-id.md#domain-types), owned by the domain admin. + `alice.org1.com` and `bob.org2.io` belong to Organization Terminus Names, and are owned by the respective users. + +- **Entity**
+ The `Application Score` belongs to the [Entity Domain](/manual/concepts/olares-id.md#domain-types), and is owned by the applicant of the entity. Organization admins and users can refer to [Domain Management](../contract/manage/contract.md#register-did) to manage their own nodes and sub-nodes. + +:::info +After the project stabilizes, ownership will be transferred to the multisig address of the DAO organization by the Terminus team. +::: + +## Tag + +The [Tag](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TagRegistry.sol) mechanism allows the [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol) contract to extend the metadata stored on nodes. + +For example, if you are an enterprise managing an organizational domain, and you want to add the attribute employee-id to each employee under the organization, you need to extend based on Tags. + +Tag system allows you to freely store data types such as `uint`, `int`, `address`, `boolean`, `bytes`, `string`, `structure`, `fixed length array`, `variable length array` on-chain in a specific encoding format (ABI). Before reading or writing data, you need to define the data type. The data type you define will apply to itself and all its child nodes. The information of **definer, user, and Tag name** is used to index a unique piece of data. + +:::info Note + +For complex structures or arrays, as well as cases where complex structures and arrays are nested within each other, if data is written in units of Tags each time, it will result in huge useless gas consumption. Therefore, we have implemented the functionality of updating a single field or operating a single array separately in the system. When performing single updates, in addition to **definer, user, and Tag name**, you also need to provide the **path** of the data, which is the variable name inside the structure. +::: + +### Customized Tags + +| Field | Description | +| ---------- | ----------------------------------------------------------------------------------------------------------------------- | +| name | Name of this tag | +| did | The DID that defines this tag | +| abiType | The data type of this tag, following the encoding specifications of **abi**, also supports defining a complex structure | +| fieldNames | When defining a complex structure, the names of internal substructures or data are flattened in a two-dimensional array | + + +::: tip NOTE +Owner/did as a custom tag is only effective for the node and its sub nodes. +::: + +### Tagger + +Tagger is one of the necessary pieces of information inside each Tag. It represents the unique entity with permission to modify the Tag value, which can be a wallet address or a contract. Tagger may change frequently. + + +> [!NOTE] +> We recommend that you use contracts as Taggers. +> +> - Referring to the official implementations of several Taggers, you can utilize DID contracts for comprehensive operator identity authentication and also achieve more refined custom permission controls. +> - For complex Tag structures or data content with special specifications, setting the Tagger as a contract can verify the data format on-chain or establish more comprehensive custom rules. For example, for the value of RSAPubKey in the official Tag, we perform validation of bytes data in Pkcs8 ASN.1 format on-chain to prevent setting values that cannot be parsed. + +## Use Cases + +Some Taggers are provided under the Root node: + +- RSAPubKey: Users can declare RSA public keys, and third parties can send them private messages based on this public key. +- AuthAddresses: Users can declare the wallet addresses they own. +- DNSARecord: Users can declare the DNS A records of Edge nodes. + +:::info About AuthAddresses +The following systems rely on this Tag's data operation: + +- Setting an Avatar + +When setting an avatar in the system, you can choose any NFT image you own as an avatar. The standard for determining if you own an NFT is whether the address of the owner exists in AuthAddresses. + +- Otmoic lp + +Otmoic lp operates as an account with TerminusName. When signing transaction information, it verifies whether the signer's address exists in AuthAddresses. + +Because AuthAddresses involve another wallet, simply verifying the sender of the transaction is not credible. Therefore, we have designed the following operation plan: + +Use the declared address and DID owner to sign the following information in compliance with the EIP712 standard and submit it to the contract for verification within a limited time (30 minutes after signing). + +```json +{ + "address": "0x10FE2771907B0c4245695daD7e9Ed064d45860f8", + "algorithm": 0, // 0: ECDSA + "domain": "olivia.myterminus.com", + "signAt": "1714287578", + "action": 0 //0: Add 1: Remove +} +``` + +::: + + +# Reputation + +We can create highly flexible [reputation](/manual/concepts/reputation.md) protocols based on Taggers. + +In implementing an on-chain Reputation system, the most crucial elements are: + +- Abstracting and representing the object to be evaluated +- Evaluating the object and storing necessary information +- Authenticating the evaluator's identity + +Regarding these elements, TerminusDID provides a comprehensive solution. We can use Individual and Entity types of DID to represent the object to be evaluated, use Tags to store extended metadata, and utilize TerminusDID's built-in permission management features to verify identities. Learn more in the following two cases. + +## Otmoic Trader Reputation + +Otmoic's reputation contract uses DID owner's EIP712 signature for identity verification, and then stores the complain did in the `complaints` field of the `otmoic.reputation` Entity. + +:::info Deployment + +1. Create the entity`otmoic.reputation` in the TerminusDID contract. +2. Define a Tag named complaints. +3. Deploy Otmoic Trader Reputation [contract](https://optimistic.etherscan.io/address/0xE924F7f68D1dcd004720e107F62c6303aF271ed3) +4. Set the Tagger of complaints to Otmoic Trader Reputation. + ::: + +:::info Usage + +1. Use DID owner to sign the transaction info following EIP712 +2. Submit transaction info and signature to Otmoic Trader Reputation + ::: + +:::info Structure + +```mermaid + flowchart LR + + otmoic{{OtmoicReputation}} + did{{TerminusDID}} + complaints[/tag-complaints/] + otmoicdid((otmoic.reputation)) + + otmoic-- Authentication -->did + did-.->otmoicdid + otmoicdid-.-complaints + otmoic-- read/write -->complaints +``` +::: + +## Application Reputation + +1. Define the Tag named `ratings` and set Tagger as the Application Reputation contract +2. When there is a new version for an app, create **`..app.myterminus.com`** on the blockchain. +3. Users sign the comment/ rating info, and submit to the Application Reputation contract. +4. The Application Reputation contract saves the rating info into Ratings of `..app.myterminus.com`, and publish the comment info in the form of event + +:::info + +```mermaid + flowchart TD + + app((app.myterminus.com)) + appname((appname.app.myterminus.com)) + version1((version1.appname.app.myterminus.com)) + version2((version2.appname.app.myterminus.com)) + reputation{{TerminusAppMarketReputation}} + ratings[/tag-ratings/] + version1ratings[/version1-tag-ratings/] + event[[event]] + + app-->appname + appname-->version1 + appname-->version2 + app-.->ratings + ratings-.-version1ratings + version1-.-version1ratings + reputation-.- read/write -.->version1ratings + reputation-.->event + +``` + +::: diff --git a/docs/developer/contribute/olares-id/contract/did/design.md b/docs/developer/contribute/olares-id/contract/did/design.md new file mode 100644 index 000000000..8ad7641a6 --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/did/design.md @@ -0,0 +1,278 @@ +--- +outline: [2, 3] +--- + +# DID + +## Design of DID + +### Data Contained in DIDs + +#### id + +Each DID is also a NFT (following **ERC-721** standard) and `id` is its unique identifier calculated by `keccak256(name)`. + +#### did +Derived from mnemonic phrases, used for authentication in systems relying on DIDs. + +#### owner + +Also derived from mnemonic phrases (following **BIP-44** standard) and used for authentication (mostly on-chain contracts). + +#### note + +DIDs have the following kinds for now: + +- Individual +- Organization +- Entity + +:::info Naming rules of TName +A valid label of TName, i.e. each part separated by `.`: + +- is a well-formed non-empty UTF-8 sequence; and +- contains only Unicode code points in category L, M, N, P, S; and +- does not contain Unicode code points in the following ranges: + - Full Stop (U+002E) + - Mongolian Free Variation Selectors (U+180B..U+180D) + - Variation Selectors (U+FE00..U+FE0F) + - Replacement Characters (U+FFFC..U+FFFD) + - Variation Selectors Supplement (U+E0100..U+E01EF). +- is case-sensitive, e.g. `MAX.com` and `max.com` are different TNames. +- supports multiple characters including Chinese, e.g. `博物馆.中国` + Ref: https://www.compart.com/en/unicode/category + ::: + + +### Tag System + +In addition to basic data, we hope to maintain some states or information in DIDs. That's why we implemented the tag system. + +#### how to use + +1. Define a tag +2. Write to the tag + +> [!NOTE] +> The definition and structure of tags are complicated. Refer to the technical details of the contract if you are interested. +> Here we briefly introduce the information in a tag definition. +> +> - name: the name of this tag +> - did: the DID that defines this tag +> - abiType: the data type of this tag, which follows the Solidity ABI specification and supports complicated structures +> - fieldNames: the field names of structs inside this tag, flatten as a 2D string array using pre-order traversal + +#### the scope of tags + +Every tag is only applicable to the DID under which it was defined and its subdomains. +For example, if the tag `employeeId` was defined in DID `a-certain-company.com`. Its subdomain `james.a-certain-company.com` can set `employeeId` value to `"001"` for itself. If the DIDs who have neither defined the tag nor is a subdomain of the definer, e.g. `another-company.com` and `emma.another-company.com`, cannot set the tag value. + +```mermaid + graph TB + + a-certain((a-certain-company.com)) + another-company((another-company.com)) + emma((emma.another-company.com)) + james((james.a-certain-company.com)) + olivia((olivia.a-certain-company.com)) + employee-id[/employee-id/] + + a-certain-->james + a-certain-->olivia + another-company-->emma + a-certain-.-employee-id + employee-id-.->james + employee-id-.->olivia +``` + +#### taggers + +The tagger is part of necessary information in each tag. Unlike the fixed definition, taggers can be changed. +A tagger represents the only person or program that has the authority to modify the tag value. It can be a wallet address or smart contract. + +> [!NOTE] +> We recommend you to use smart contracts for taggers. +> +> - You can utilize the Terminus DID contract for complete operator authentications, while achieving more fine-grained custom access control. Please refer to some official tagger implementations. +> - For complicated tag structures or data with special formats, using contract taggers supports verifying data format on chain and customizing the rules. For example, in the official tagger we will verify the bytes data in PKCS8 ASN.1 format on chain to prevent accidentally setting unparsable values for the `RSAPubKey` tag. + +### Who to Create DIDs + +Since not everyone has enough gas for on-chain operations and is willing to use the owner address of existing DIDs, we offer the choice of sending tx by official forwarders on your behalf. Of couse you can also operate on your own if willing. + +### Priviledges of DIDs + +A DID has management priviledge over itself and all its subdomains. For 3rd-level domains which is registered directly, e.g. `a.b.c` without the registration of `b.c`, the owner of `b.c` will be set to `0x0...00d1d` and it is managed by the official. + +### Introduction to processes and concepts + +The extended information of TNames is managed by the tag system of the Terminus DID contract. Every tag has not only a name but also a tag type. For now, supported types include `int`, `uint`, `bool`, `string`, `address`, `bytes`, `bytesN`, `array`, `arrayN` and `tuple`. Tuples supports additional field names. +Since tags are bound to TNames, the steps for setting a tag are: + +- Define a tag in a TName with the tag name, tag type and field names in tuples. Setting the field names is not trivial so refer to the documentation "DIDv2.3Tag 类型注册流程介绍" for details. + +Code example + +```Solidity +function defineTag( + string calldata domain, + string calldata name, + bytes calldata abiType, + string[][] calldata fieldNames +) public +``` + +- Set the tagger which is responsible for setting this tag. The tagger can be EOA or a contract address. Complicated validation logic can be implemented in contract taggers. + +Code example + +```Solidity +function setTagger(string calldata domain, string calldata name, address tagger) public +``` + +- Next you can perform CRUD of this tag on the definer and its subdomains. + +```Solidity +function addTag(string calldata from, string calldata to, string calldata name, bytes calldata value) public +function removeTag(string calldata from, string calldata to, string calldata name) public +function getTagElem(string calldata from, string calldata to, string calldata name, uint256[] calldata elemPath) + public + view +returns (bytes memory) +function updateTagElem( + string calldata from, + string calldata to, + string calldata name, + uint256[] calldata elemPath, + bytes calldata value +) public +function getTagElemLength( + string calldata from, + string calldata to, + string calldata name, + uint256[] calldata elemPath +) public view returns (uint256) +function pushTagElem( + string calldata from, + string calldata to, + string calldata name, + uint256[] calldata elemPath, + bytes calldata value +) public +function popTagElem(string calldata from, string calldata to, string calldata name, uint256[] calldata elemPath) public +``` + +Among these + +- `from` is the TName that defines this tag +- `to` is the TName to set this tag +- `name` is the tag name +- `value` is the bytes value after `abi.encode` +- `elemPath` is provided for `array` and `tuple` to access a single element. For other types just set it to an empty array. Its value is treated like indices of multi-dimensional arrays (think `tuple`s as arrays too). For example, the following type `Student` has 4-level nested tuples, and we can set `elemPath` to `[1,2,1,0,0]` to read or update `Student s -> Class class -> Teacher[1] teachers -> People info -> string name`. Note that we only have 4-level nested tuples but `elemPath` has length 5 because `teachers` is an array and adds another nesting level. + +```Solidity +struct Student { + People info; + Class class; +} + +struct Class { + uint8 grade; + uint8 classNum; + Teacher[] teachers; +} + +struct People { + string name; + uint8 age; + string gender; +} + +struct Teacher { + People info; + string subject; +} +Student s; +``` + +- The Terminus DID contract provides a set of special tags, known as the official tags. It is defined in the empty TName `""` and its tagger is specified as the `RootTagger`. All TNames can set official tags and we'll introduce the detailed access control policy later. + +### Access Control of Tags + +1. Defining tags in a TName, i.e. setting the tag name and type + +- Official tags: the `operator` has permission +- Other tags: the owner of this TName has permission + Defining tags can fail in the following situations: +- A tag name can only be defined once in one TName, no duplicates +- Tag names and field names of tuples must start with [a-z] and only contain [a-zA-Z0-9] +- The bytes representation of a tag type cannot exceed length 31 +- The tag type must follow the type constraints in the `ABI` library +- The value of `fieldNames` must match tuple types in the definition +- A tuple cannot have duplicate field names + +2. Setting the tagger: + +- Official tags: the `operator` has permission +- Other tags: the owner of this TName has permission + +3. Setting the tag: + + Taggers are responsible for access control of setting tags. Next we introduce the cases of official tags. + +## Registration Rules and Access Control + +From the contract's perspective, for now only the operator can register top-level TName. Normal registration is done by calling the `register` interface with arguments including the owner of the TName and some metadata. The metadata is immutable after registration. Sub-TNames can be registered by the operator or the owner of one of its parent TNames. +That said, registration can only be performed by the following roles: + +- The `operator` of the contract +- The owner of a parent TName can register a sub-TName + Registration can fail in the following cases: + - when TName is not top-level: the parent TName is not registered yet or the parent's metadata specifies it cannot have sub-TNames + - the TName contains an invalid label + - the TName is already registered + - the owner of the TName is specified as zero address + +**Code example**: + +```Solidity +struct Metadata { +string domain; +string did; +string notes; +bool allowSubdomain; +} + +function register(address tokenOwner, Metadata calldata metadata) public returns (uint256 tokenId) +``` + +After registration, the contract will mint a ERC-721 NFT with a returned token ID (`tokenId`). It is the Keccak-256 hash of the TName string. + +**Code example**: + +```Solidity +function tokenId(string memory domain) internal pure returns (uint256) { +return uint256(keccak256(bytes(domain))); +} +``` + +Since the NFT is ERC721-compatible, it supports standard ERC-721 operations like `transferFrom` and `approve`. So the ownership can be transferred by these addresses: + +- the owner of the TName +- the delegator of the owner +- addresses approved by the owner + +The Terminus DID contract adds two addresses that have transfer privilege: + +- `operator` of the contract +- the owner of the parent TName + +## Roles of the Contract + +The Terminus DID contract has an owner for upgrading itself. It also has a superuser, i.e. the `operator`, to facilitate configuration. Every TName has its owner. + +The privileges of the contract owner include: + +- setting the operator address +- transferring ownership of the contract +- upgrading the contract diff --git a/docs/developer/contribute/olares-id/contract/did/faq.md b/docs/developer/contribute/olares-id/contract/did/faq.md new file mode 100644 index 000000000..2801588e8 --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/did/faq.md @@ -0,0 +1,11 @@ +# FAQ + +## Transaction Fee + +When you apply for an Olares ID, we can afford the transaction fee for calling the contract. The rough process is: + +- You provide us the data and signature signed by your private key +- We send the transaction to the smart contract +- The blockchain records your data after signature verification + +If you need to manage data under your domain in the future, you should call the contract via MetaMask. Alternatively, you can log in to Olares Space using LarePass and pay the the transaction fee by yourself. diff --git a/docs/developer/contribute/olares-id/contract/did/official-taggers.md b/docs/developer/contribute/olares-id/contract/did/official-taggers.md new file mode 100644 index 000000000..b11d8028b --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/did/official-taggers.md @@ -0,0 +1,18 @@ +# Official Taggers + +## RootTagger + +So far we have defined the following tags and use `RootTagger` as their taggers: + +- rsaPubKey: the RSA public key of a TName + type: `bytes`; access: the operator, the owner of the TName, and the owner of a parent TName +- dnsARecord: the IP address of a TName + type: `bytes4`; access: the operator, the owner of the TName, and the owner of a parent TName +- latestDID: the latest DID of a TName (this is added because the metadata is immutable) + type: `string`; access: the operator, the owner of the TName, and the owner of a parent TName +- authAddresses: the addresses controlled by the owner of a TName + type: `tuple(uint8,address)[]`; access: anyone with EIP-712 signatures of the owner of the TName and the added address + +## AppStoreReputation + +There is another special tagger `AppStoreReputation` for the tag `ratings` with type `tuple(string,uint8)[]` defined in the TName `app.myterminus.com`. It provides on-chain storage for ratings of apps in Terminus OS. Each app has a corresponding sub-TName `..app.myterminus.com` where anyone who has a TName can submit ratings for these apps. diff --git a/docs/developer/contribute/olares-id/contract/did/release-history.md b/docs/developer/contribute/olares-id/contract/did/release-history.md new file mode 100644 index 000000000..c28df135c --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/did/release-history.md @@ -0,0 +1,21 @@ +# Release History + +## V2.0.0 + +Implement core architecture of DID module in Terminus DID + +## V2.1.0 + +Add tag system without definition + +## V2.2.0 + +Upgrade tag system to include type definition + +## V2.3.0 + +Optimize contract structure and reduce core contract size + +## V2.3.1 + +Bug-fix: Revert instead of going on with zero address when EIP-712 signature recover fails diff --git a/docs/developer/contribute/olares-id/contract/manage/contract.md b/docs/developer/contribute/olares-id/contract/manage/contract.md new file mode 100644 index 000000000..5083ede64 --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/manage/contract.md @@ -0,0 +1,104 @@ +--- +outline: [2, 3] +--- + +# Call the contract directly + +## DID + +### Get metadata + +There are two interfaces for fetching the metadata of a DID - `getMetadata(tokenId)` and `getMetadata(name)`. + +#### Return value + +```json +[ + "james.myterminus.com", // name + "did:key:z6MkpLwxcTwhj4MRm4eKhvBadK45qHr5QEYHUXNyhCfkXJ9U#z6MkpLwxcTwhj4MRm4eKhvBadK45qHr5QEYHUXNyhCfkXJ9U", // DID derived from mnemonic phrases + "OrganizationalUser", // DID type + true // allowed to create subdomains? +] +``` + +### Get the owner of a domain + +Call `ownerOf(tokenId)` to get the on-chain controller address of a DID. + +### Get token by index of creation + +Call `tokenByIndex(index)` to get the token with a specified index. It returns a **token ID**. + +### Get token by owner and index + +Although we disallow owning multiple DIDs by a single wallet from the business' perspective, the contract allows this considering possible ownership transferring and NFT trading in the future. In this case, `tokenOfOwnerByIndex(owner, index)` can be called to get the token owned by a specified address with a specified index. It returns a **token ID**. + +### Register DID + +The owner of a domain can call `register(owner, MetaData(domain, did, note, allowSubdomain))` to register its subdomains. + +> [!NOTE] +> The first parameter **owner** is the specified owner of the new DID and the second parameter is a struct of metadata containing. +> +> - domain: the complete domain name of the new DID, which is also a Olares ID +> - did: the DID derived from the owner's wallet +> - note: notes about the new DID, used by off-chain systems for categorization +> - allowSubdomain: whether to allow the new DID to register subdomains +> +> The metadata cannot be changed after registration. If the ownership is transferred in the future, the new DID record will be written to the `latestDid` tag. + +## Tag + +### Get the number of tags defined by a name + +`getDefinedTagCount(name)` returns how many tags are defined by a specified TName. + +### Get tag name + +Used with the above interface, `getDefinedTagNameByIndex(name, index)` returns a single tag name and `getDefinedTagNames(name)` returns all tag names defined by a specified TName. + +### Structured tag + +If a tag type is a complicated structure instead of primitive value, call `getTagType(name, tagName)` to query the structure definition and then call `getFieldNamesEventBlock(fieldNamesHash)` with previously returned **fieldNamesHash** to get the block number at which this tag is defined. Finally, use the `ethers` library to get field names in the definition. + +> [!NOTE] +> The interface for querying tag type returns an encoded bytes of the ABI type, which should be parsed according to the code table. Querying field names can be complicated and error-prone, so we recommend to use functions in the SDK to fetch data about tags instead of calling the contract manually. + +Call `getTagElem(definedDidName, valueDidName, tagName, elemPath)` to get the value of a tag after getting the tag type. + +> [!NOTE] +> +> - definedDidName: the TName defining this tag +> - valueDidName: the TName whose tag value is desired +> - elemPath: path selector to read an inner element for tuples or arrays (`[]` for reading the full tag) +> +> This interface returns ABI-encoded data which should be parsed according to the tag type. +> It is also recommended to use SDK instead of calling the contract manually. + +### Define a tag + +Call `defineTag(didName, tagName, abiType, fieldNames)` with the owner of `didName` to define a tag. + +> [!NOTE] +> +> - abiType: data type of this tag following our **ABI** code format, which supports complicated structures +> - fieldNames: the field names of structs inside this tag, flatten as a 2D string array using pre-order traversal + +### CRUD + +> [!NOTE] +> We recommend to interact with the tagger contract instead of using the following interfaces to perform tag operations. + +- Create - Call `addTag(defineDidName, valueDidName, tagName, value)` to add a tag. + +- Update - Call `updateTagElem(defineDidName, valueDidName, tagName, elemPath, value)` to update a piece of data in a tag. + +- Delete - Call `removeTag(defineDidName, valueDidName, tagName)` to delete a tag. This deletes a tag set on a DID instead of deleting the tag definition. + +- Array operations - If the tag type contains an array, call `popTagElem(defineDidName, valueDidName, tagName, elePaths)` and `pushTagElem(defineDidName, valueDidName, tagName, elePaths, value)` to perform array-specific operations. + +> [!NOTE] +> +> - defineDidName: the TName defining this tag +> - valueDidName: the TName on which the tag value is set +> - value: ABI-encoded tag value diff --git a/docs/developer/contribute/olares-id/contract/manage/environment.md b/docs/developer/contribute/olares-id/contract/manage/environment.md new file mode 100644 index 000000000..d5604a6c2 --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/manage/environment.md @@ -0,0 +1,23 @@ +--- +outline: [2, 3] +--- + +# Environment + +## Sepolia Optimistic + +- TerminusDID: 0x4c8c98e652d6a01494971a8faF5d3b68338f9ED4 +- RootTagger: 0xaA5bE49799b6A71Eda74d22D01F7A808aFf41b3f +- LibABI: 0xdc9e8faDe38eE9E2Eb43761f1553CD2360ecAEac + +## Optimistic + +- TerminusDID: 0x5da4fa8e567d86e52ef8da860de1be8f54cae97d +- RootTagger: 0xe2eaba0979277a90511f8873ae1e8ca26b54e740 +- LibABI: 0x9ae3f16bd99294af1784beb1a0a5c84bf2636365 + +> [!NOTE] +> RootTagger is the tagger for the following official tags: - DNSARecord - RSAPubKey - LatestDid - AuthAddress + +> [!NOTE] +> LibABI is an independent library contract, providing functions like ABI type encoding, data conversion etc. diff --git a/docs/developer/contribute/olares-id/contract/manage/sdk.md b/docs/developer/contribute/olares-id/contract/manage/sdk.md new file mode 100644 index 000000000..baa0b5eed --- /dev/null +++ b/docs/developer/contribute/olares-id/contract/manage/sdk.md @@ -0,0 +1,299 @@ +--- +outline: [2, 3] +--- + +# Management with SDK + +## DID + +### Get all DIDs + +Sometimes we need complete data for statistical or other reasons. The following `fetchAll` method utilizes the contract interfaces to get complete data. Although it gets the result directly from on-chain interfaces instead of traversing Ethereum events, this can be time-consuming as the amount of data is large. + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const dids = await did.fetchAll() + + console.log('dids:', dids) + + console.log('format dids:', await did.formatDatas(dids)) +} + +fetch() +``` + +> [!NOTE] +> If running in development environment and logging is on, the fetching progress is shown during execution. + +#### Fast fetch + +For your convenience, the SDK provides two functions `formatDatas` and `loadDatas`. The data returned by `formatDatas` can be stored and it can be loaded by `loadDatas` next time to reduce syncing duration. A simpler way is to access the `/all` endpoint in the official **did-support** service, which can also be loaded by `loadDatas`. + +### Query specific DID + +After reading the above contract interfaces, you should notice that the contract does not provide a single interface for fetching complete data related to a DID. So we simplified the design of interfaces in the SDK, where `fetchDomain` returns complete data for a DID. + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + console.log('did:', domain) +} + +fetch() +``` + +#### Fast query + +After you execute `loadDatas` in the above SDK examples, `fetchDomain` will first try to match local data and only fetch data on-chain if there is no data for this DID on local machine. + +#### Update DID + +If you are worried that fast query does not return the latest data, use `updateDomain` or `updateDomainById` to update local data. + +#### Fuzzy matching + +Like fast query, you can use the fuzzy matching function in SDK after loading data locally. The following two functions only match the local data: + +```Typescript +import DID from 'did-contract-developer-components' +//... code + +// Query DID by owner and return all subdomains +const domainsByOwner = DID.Domain.findSubtreesByOwner(owner, did.treesCache) + +//Query DID by did and return all subdomains +const domainsByDid = DID.Domain.findSubtreesByDid(did, did.treesCache) + +``` + +## Tag + +### Get all tags of a DID + +Unlike calling the contract directly, this function returns data with parsed tag structure and struct field names. + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + const tags = await DID.Domain.fetchAllTagType(domain, did.getContractDID()) + + console.log('tags:', tags) +} + +fetch() +``` + +### Get all tag values of a DID + +Like the above method, this function returns parsed data with JSON tag values. + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + await DID.Domain.fetchAllTagType(domain, did.getContractDID()) + + const tags = await DID.Domain.fetchAllTagValue(domain, did.getContractDID()) + + console.dir(tags, {depth: null}); +} + +fetch() +``` + +### Define tag + +Using SDK to define a tag, you can construct the inner structure of the tag type with an object-oriented approach without worrying about the encoding. The following examples include most common data types. + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const defineTag = async () => { + + // tag name: simpleTag + const tagName = 'simpleTagBox' + + // tuple + const testTuple = new DID.Tag.TagValueTypeTuple(undefined, undefined, true); + + // uint + const testUint = new DID.Tag.TagValueTypeUint(undefined, undefined, true); + testUint.setSize(8) + + // address + const testAddress = new DID.Tag.TagValueTypeAddress(undefined, undefined, true); + + // array
+ const testArrayAddress = new DID.Tag.TagValueTypeArray(undefined, undefined, true); + testArrayAddress.setBuliderType(testAddress) + + // bool + const testBool= new DID.Tag.TagValueTypeBool(undefined, undefined, true) + + // bytes + const testBytes = new DID.Tag.TagValueTypeBytes(undefined, undefined, true) + + // int + const testInt = new DID.Tag.TagValueTypeInt(undefined, undefined, true) + testInt.setSize(256) + + // flarray + const testFlarrayInt = new DID.Tag.TagValueTypeFlarray(undefined, undefined, true) + testFlarrayInt.setBuliderType(testInt) + testFlarrayInt.setSize(3) + + // flbytes + const testFlbytes = new DID.Tag.TagValueTypeFlbytes(undefined, undefined, true) + testFlbytes.setSize(5) + + // string + const testString = new DID.Tag.TagValueTypeString(undefined, undefined, true) + + testTuple.setField('testUint', testUint) + testTuple.setField('testArrayAddress', testArrayAddress) + testTuple.setField('testBool', testBool) + testTuple.setField('testBytes', testBytes) + testTuple.setField('testFlarrayInt', testFlarrayInt) + testTuple.setField('testFlbytes', testFlbytes) + testTuple.setField('testString', testString) + + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + await DID.Domain.defineTag(domain, tagName, testTuple, did.getContractDIDByPrivateKey('you-private-key'), did) +} + +defineTag() +``` + +### Set tagger + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const setTagger = async () => { + + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + const [tag] = domain.tags.filter(tag => tag.name == 'simpleTagBox') + + DID.Domain.setTagger(tag, 'you-tagger-address', did.getContractDIDByPrivateKey('you-private-key')) +} + +setTagger() +``` + +### Set tag value + +Like defining a tag above, when using SDK to set tag value, you only need to pass in suitable JSON data without worrying about the encoding. The tag types in the following examples are the same as the tag definition section above. + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const setTagValue = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + console.log(domain) + const [tag] = domain.tags.filter(tag => tag.name == 'simpleTagBox') + const tagType = await DID.Domain.fetchTagStructure(tag, did.getContractDID()) + console.dir(tagType, {depth: null}) + + const ba1 = ethers.hexlify(Uint8Array.from([1, 2, 3])) + const ba2 = ethers.hexlify(Uint8Array.from([10, 18, 19])) + + const newData = { + testbox: { + testUint: 1, + testArrayAddress: ['0xF18B2Ea28c722CA87f951F5bF5327b66a7dd72A3', '0xecBA1d33b889f66ad426535f970d1E033ba5c79C'], + testBool: true, + testBytes: '0x0102030405' , + testFlarrayInt: [2, 3, 4], + testFlbytes: '0x0a0b0c0d0e', + testString: 'ok' + } + } + console.log('newData', newData) + + const call = await DID.Tag.doEncode(tagType, newData) + console.log('call', call) + + //set + const resp = await DID.Domain.setValue(tag, call, did.getContractDIDByPrivateKey('you-private-key')) +} + +setTagValue() +``` diff --git a/docs/developer/contribute/olares-id/index.md b/docs/developer/contribute/olares-id/index.md new file mode 100644 index 000000000..423d983a1 --- /dev/null +++ b/docs/developer/contribute/olares-id/index.md @@ -0,0 +1,26 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: "Snowinning Protocol" + text: "" + tagline: Building a Self-Sovereign Internet + actions: + - theme: brand + text: What is Snowinning + link: /protocol/overview.md + - theme: alt + text: Vist GitHub + link: https://github.com/beclab/terminus + +features: + - title: Snowinning Protocol + details: A decentralized identity and credit system that facilitates secure, trustless exchanges of information and value. + - title: Smart Contract + details: Snowinning Protocol's smart contract consists of DID Registry and the extended reputation systems based on DID. + + - title: Verifiable Credential (VC) + details: Fully ratified W3C standard that work together with DIDs to enable trustless, secure interactions. +--- + diff --git a/docs/developer/contribute/olares-id/verifiable-credential/issuer.md b/docs/developer/contribute/olares-id/verifiable-credential/issuer.md new file mode 100644 index 000000000..72bc14cc9 --- /dev/null +++ b/docs/developer/contribute/olares-id/verifiable-credential/issuer.md @@ -0,0 +1,186 @@ +# Issuer + +![alt text](/images/developer/contribute/issuer.png) + +The following is the issuer process: + +1. Holder gets the Manifest from Issuer. +2. Holder signs it and submits the Application. +3. Issuer reviews the Application automatically or manually. +4. Holder receives the review results from the Issuer and either gets the VC if approved or a reason if rejected. + +## Manifest + +This file will be returned to Holder. +`outputDescriptors` is given for wallets to display VCs. +`presentationDefinition` is in fact the later `manifest_presentation` file, used to confirm the format of Application submitted by users. + +```json +{ + "name": "Facebook Verifiable Credential Manifest", + "description": "Facebook Verifiable Credential Manifest", + "issuerDid": "", + "issuerName": "", + "outputDescriptors": [ + { + "id": "", + "schema": "", + "name": "Facebook Verifiable Credential Manifest", + "description": "Facebook Verifiable Credential Manifest", + "display": { + "title": { + "path": ["$.credentialSubject.name", "$.vc.credentialSubject.name"], + "schema": { "type": "string" } + }, + "subtitle": { + "path": ["$.credentialSubject.title", "$.vc.credentialSubject.title"], + "schema": { "type": "string" } + }, + "description": { + "path": [ + "$.credentialSubject.description", + "$.vc.credentialSubject.description" + ], + "schema": { "type": "string" } + }, + "properties": [ + { + "path": ["$.credentialSubject.id", "$.vc.credentialSubject.id"], + "schema": { "type": "string" }, + "label": "ID" + }, + { + "path": [ + "$.credentialSubject.email", + "$.vc.credentialSubject.email" + ], + "schema": { "type": "string" }, + "label": "Email" + } + ] + }, + "styles": { + "background": { + "color": "#FFFFFF" + }, + "text": { + "color": "#000000" + } + } + } + ], + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "presentationDefinition": {} +} +``` + +## Manifest Presentation + +Issuer uses this file to validate the format of the Application submitted by the Holder. + +```json +{ + "name": "Facebook Manifest Presentation Definition", + "purpose": "Provide your token required to Facebook", + "inputDescriptors": [ + { + "id": "token", + "name": "Access Token", + "purpose": "Provide your token required to Facebook", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.token"] + } + ], + "subject_is_issuer": "preferred" + } + } + ], + "author": "" +} +``` + +## Application Verifiable Credential + +Although users only need `manifest_presentation` to construct VC data in client, servers need a schema to verify whether `manifest_presentation` meets the format requirements. +This file will be returned to Holder so that Holder knows the format of data required to submit for verification. +In the scenarios of Facebook, Twitter and Gmail, users login in client and get the access token, then submit it to the Issuer server, which can get the basic information of the user with the access token from e.g. the Facebook server etc. So users only need to submit the token which is simple. +But in the scenario of KYC, users need to submit full name, ID photo or even verification video etc., and the fields in this file can become much more complicated. + +```json +{ + "author": "", + "name": "Facebook Verifiable Credential Request Schema", + "schema": { + "$id": "facebook-schema-1.0", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Facebook Verifiable Credential Schema", + "type": "object", + "properties": { + "token": { + "type": "string" + } + }, + "required": ["token"], + "additionalProperties": true + }, + "sign": false +} +``` + +## Verifiable Credential + +The VC format returned to Holder by Issuer + +```json +{ + "author": "", + "name": "Facebook Verifiable Credential Schema", + "schema": { + "$id": "facebook-schema-1.0", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Facebook Verifiable Credential Schema", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "title": { + "type": "string" + }, + "description": { + "type": "string" + }, + + "facebook_name": { + "type": "string" + }, + "profile_image": { + "type": "string" + }, + "email": { + "type": "string" + }, + "facebook_id": { + "type": "string" + }, + "picture_is_silhouette": { + "type": "boolean" + } + }, + "required": ["name", "title", "description", "facebook_name"], + "additionalProperties": true + }, + "sign": false +} +``` diff --git a/docs/developer/contribute/olares-id/verifiable-credential/olares.md b/docs/developer/contribute/olares-id/verifiable-credential/olares.md new file mode 100644 index 000000000..a5153b6fe --- /dev/null +++ b/docs/developer/contribute/olares-id/verifiable-credential/olares.md @@ -0,0 +1,46 @@ +# Use case with Olares + +While DIDs solve the issue of identity in a decentralized network, they are typically difficult for humans to remember or use in daily situations. Olares ID provides a familiar, easy-to-remember format similar to email addresses, while still leveraging the power and security of DIDs. Each Olares ID is bound to a DID. + +## Potential fairness issues + +The **first-come, first-served** system in Olares ID registration may present some fairness issues, such as: + +1. **Fraud:** For instance, the Olares ID `elonmusk@myterminus.com` might be registered by someone who isn't actually Elon Mask. +2. **Speculation:** Pre-registration of popular names could lead to speculation, potentially boosting early network activity, but at the cost of fairness. + +## VC process for Olares ID + +To address the potential faireness concerns, we adopted principles from **Self-Sovereign Identity (SSI)** services proposed by the Web5 team, along with the [VC process](/manual/concepts/vc.md#verification-process) of Olares ID. This led us to design an **Issuer and Verifier** process to assist users in applying for a **Olares ID**. + +![alt text](/images/developer/contribute/vc-process.jpeg) + +### Gmail issuer service + +We utilize Google's OAuth process to facilitate the issuance of **Verifiable Credentials (VCs)**. The simplified process is as follows: + +1. Alice logs into her Gmail account via OAuth in LarePass, the wallet client. +2. Google returns the OAuth credentials to LarePass. +3. LarePass submits the OAuth credentials to the Issuer. +4. The Issuer confirms the validity of the credentials with Google's servers and retrieves basic information (e.g., email name). +5. The Issuer issues a VC to Alice that matches the local part of her Gmail address. + +Alice can now store the issued VC in LarePass. + +:::tip NOTE +- Throughout the process, Alice only reveals basic account data within the scope of the credential authorization to LarePass and the Issuer service, with password and privacy protection ensured by Google's OAuth protocol. +- All the code for setting up a Gmail Issuer Service or other Web2 service Issuer Services are open sourced on GitHub. +::: + +### Olares ID verifier service + +Here's how the **Verifier Service** works on the Olares end: + +1. Alice packages her DID, Olares ID, and Gmail VC into a **Verifiable Presentation (VP)** and submits the VP with its signature to the Verifier Service. +2. The Verifier Service checks: + - The signature's validity. + - The validity of the VC in the VP. + - Whether the Olares ID can be registered on the blockchain (conflicts may arise if multiple channels, such as Gmail and Twitter, are used for VC information). +3. After all checks pass, the Verifier Service submits Alice's information to the blockchain and covers the Gas fees. + +At this point, Alice successfully obtains her **Olares ID**. For example, if you apply with the Gmail address "hello@gmail.com", you'll receive the Olares ID "hello@myterminus.com" once all checks are completed. \ No newline at end of file diff --git a/docs/developer/contribute/olares-id/verifiable-credential/overview.md b/docs/developer/contribute/olares-id/verifiable-credential/overview.md new file mode 100644 index 000000000..f918d34a7 --- /dev/null +++ b/docs/developer/contribute/olares-id/verifiable-credential/overview.md @@ -0,0 +1,55 @@ +# VC Service + +The purpose of this documentation is to help you understand how to configure various schemas and create Issuers and Verifiers for your own scenarios using: +- [verifiable-credential-gate](https://github.com/Above-Os/verifiable-credential-gate) and [did-gate](https://github.com/Above-Os/did-gate) by Terminus. +- [SSI Service](https://github.com/TBD54566975/ssi-service) by the tbd team. + +::: tip +If you want to engage in lower-level development, read the [protocol standard](#reference) together with the source code in [SSI SDK](https://github.com/TBD54566975/ssi-sdk). +::: + +## Introduction + +We have learned about [VC](/manual/concepts/vc.md) and the basic process for applying VCs. + +Before we get into the implementation details, we can familiarize ourselves with the terms that we will encounter in the real communication process of Wallet, Verifier and Issuer. +| Term | Definition | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Holder | Holders are entities that have one or more verifiable credentials in their possession. Holders are also the entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. | +| Issuer | A role an entity can perform by asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder. | +| Verifier | Verifiers are entities that define what proofs they require from a Holder (via a Presentation Definition) in order to proceed with an interaction. | +| Verifiable Credential | Is a tamper-evident credential that has authorship that can be cryptographically verified. Verifiable credentials can be used to build Verifiable Presentations, which can also be cryptographically verified. The claims in a credential can be about different subjects. PEX accepts Verifiable credential in 3 forms: 1. JSON_LD which is known in our system as IVerifiableCredential, 2. JWT-Wrapped VC which is known in our system as JwtWrappedVerifiableCredential or string which is a valid Verifiable credential jwt | +| Verifiable Presentation | s a tamper-evident presentation encoded in such a way that authorship of the data can be trusted after a process of cryptographic verification. | +| Manifest | Credential Manifests are used to describe which credentials are available for issuance. | +| Application | The format provided by Holder to Issuer, including | +| Presentation Definition | Presentation Definitions are objects that articulate what proofs a Verifier requires. | +| Presentation | Data derived from one or more verifiable credentials, issued by one or more issuers | +| Submission | TBC | +| Definition | TBC | +| Schema | All different Manifest, Application, Credential, Presentation, Definition need to define Schema with JSON. The service will verify the correctness of submitted data and then go into business process. | + +## Reference + +The following reference materials come from the [SSI SDK](https://github.com/TBD54566975/ssi-sdk) project. + +### Specifications + +Here are a set of references to specifications that this library currently supports. It is a dynamic set that will change as the library evolves. + +- [Decentralized Identifiers (DIDs) v1.0](https://www.w3.org/TR/did-core/) W3C Proposed Recommendation 03 August 2021 +- [Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/) W3C Recommendation 09 November 2021 + - Supports [Linked Data Proof](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) formats. + - Supports [VC-JWT and VP-JWT](https://www.w3.org/TR/vc-data-model/#json-web-token) formats. +- [Verifiable Credentials JSON Schema Specification](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) Draft Community Group Report, 21 September 2021 +- [Presentation Exchange 2.0.0](https://identity.foundation/presentation-exchange/) Working Group Draft, March 2022 +- [Wallet Rendering Strawman](https://identity.foundation/wallet-rendering/), June 2022 +- [Credential Manifest](https://identity.foundation/credential-manifest/) Strawman, June 2022 +- [Status List 2021](https://w3c-ccg.github.io/vc-status-list-2021/) Draft Community Group Report 04 April 2022 + +### Signing Methods + +> - [Data Integrity 1.0](https://w3c.github.io/vc-data-integrity/) Draft Community Group Report +> - [Linked Data Cryptographic Suite Registry](https://w3c-ccg.github.io/ld-cryptosuite-registry/) Draft Community Group Report 29 December 2020 +> - [JSON Web Signature 2020](https://w3c-ccg.github.io/lds-jws2020/) Draft Community Group Report 09 February 2022 +> - [VC Proof Formats Test Suite, VC Data Model with JSON Web Signatures](https://identity.foundation/JWS-Test-Suite/) Unofficial Draft 09 March 2022 This implementation's compliance with the JWS Test Suite can be found here. +> - Supports both JWT and Linked Data proof formats with [JOSE compliance](https://jose.readthedocs.io/en/latest/). diff --git a/docs/developer/contribute/olares-id/verifiable-credential/verifer.md b/docs/developer/contribute/olares-id/verifiable-credential/verifer.md new file mode 100644 index 000000000..a7f6b23ca --- /dev/null +++ b/docs/developer/contribute/olares-id/verifiable-credential/verifer.md @@ -0,0 +1,164 @@ +# Verifer Service + +Refer to [Presentation Exchange](https://identity.foundation/presentation-exchange/) +![verifier](/images/developer/contribute/verifier.png) for the process. + +## Presentation Definition + +1. The Verifier returns the file to the Holder. +2. The Holder submits a packaged file that meets the format requirements to the Verifier, after filling in the contents according to the specifications. + +```json +{ + "name": "Facebook Basic Info Presentation Definition", + "purpose": "Provide your facebook basic info", + "inputDescriptors": [ + { + "id": "name", + "name": "Name", + "purpose": "Provide vc name", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.name"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "title", + "name": "Title", + "purpose": "Provide vc title", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.title"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "description", + "name": "description", + "purpose": "Provide vc description", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.description"] + } + ], + "subject_is_issuer": "preferred" + } + }, + + { + "id": "facebook_name", + "name": "Provide your facebook name", + "purpose": "Provide your facebook name", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.facebook_name"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "profile_image", + "name": "Provide your facebook profile image", + "purpose": "Provide your facebook profile image", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.profile_image"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "email", + "name": "Provide your facebook email email info", + "purpose": "Provide your facebook email info", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.email"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "facebook_id", + "name": "Provide your facebook id", + "purpose": "Provide your facebook id", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.facebook_id"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "picture_is_silhouette", + "name": "Provide your facebook Picture is Silhouette", + "purpose": "Provide your facebook picture_is_silhouette", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.picture_is_silhouette"] + } + ], + "subject_is_issuer": "preferred" + } + } + ], + "author": "" +} +``` diff --git a/docs/developer/contribute/olares.md b/docs/developer/contribute/olares.md new file mode 100644 index 000000000..c1fa189c8 --- /dev/null +++ b/docs/developer/contribute/olares.md @@ -0,0 +1,92 @@ +# Olares + +## Directory structure + +``` +olares +|-- apps # olares built-in apps +| |-- agent +| |-- analytic +| |-- market +| |-- market-server +| |-- argo +| |-- desktop +| |-- devbox +| |-- vault +| |-- files +| |-- knowledge +| |-- nitro +| |-- notifications +| |-- profile +| |-- rss +| |-- search +| |-- settings +| |-- system-apps +| |-- wise +| |-- wizard +|-- build # olares installer +| |-- installer +| |-- manifest +|-- frameworks # system runtime frameworks +| |-- app-service +| |-- backup-server +| |-- bfl +| |-- GPU +| |-- l4-bfl-proxy +| |-- osnode-init +| |-- system-server +| |-- tapr +|-- libs # toolkit libs +| |-- fs-lib +|-- scripts # scripts for build or package the olares installer +|-- third-party # third party libs or apps integrated in olares +| |-- authelia +| |-- headscale +| |-- infisical +| |-- juicefs +| |-- ks-console +| |-- ks-installer +| |-- kube-state-metrics +| |-- notification-mananger +| |-- predixy +| |-- redis-cluster-operator +| |-- seafile-server +| |-- seahub +| |-- tailscale +``` + +## How to install + +``` +curl -fsSL https://olares.sh | bash - +``` + +## How to build + +``` +git clone https://github.com/beclab/olares + +cd olares + +bash scripts/build.sh + +``` + +Run the above scripts, you will get the debug version installer package `install-wizard-debug.tar.gz` + +## How to install debug version + +``` +mkdir -p /path/to/unpack && cd /path/to/unpack + +tar zxvf /path/to/olares/install-wizard-debug.tar.gz + +make install VERSION=0.0.0-DEBUG + +``` + +## How to uninstall + +```bash +olares-cli uninstall --all +``` diff --git a/docs/developer/contribute/overview.md b/docs/developer/contribute/overview.md new file mode 100644 index 000000000..59eb3a573 --- /dev/null +++ b/docs/developer/contribute/overview.md @@ -0,0 +1,7 @@ +# Contributing To Olares + +## Olares + +## TermiPass + +## Develop System App diff --git a/docs/developer/contribute/system-app/deployment.md b/docs/developer/contribute/system-app/deployment.md new file mode 100644 index 000000000..ffc1ba751 --- /dev/null +++ b/docs/developer/contribute/system-app/deployment.md @@ -0,0 +1,295 @@ +--- +outline: [2, 3] +--- + +# deployment.yaml + +The system application need to be installed under the `user-space` namespace. Therefore, certain modifications are required: + +1. Modify the `deployment.yaml` file in the Olares Application Chart. +2. Change the original namespace of `deployment` and `service` to `user-space-{\\{ .Values.bfl.username }}` + + ```Yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: desktop-dev + namespace: user-space-{{ .Values.bfl.username }} + ``` + +3. Add `annotations` and `labels` according to the configuration in the `deployment.yaml` file of the app in **Olares**. + + ```Yaml + metadata: + name: desktop-dev + namespace: user-space-{{ .Values.bfl.username }} + labels: + app: desktop-dev + applications.app.bytetrade.io/name: desktop-dev + applications.app.bytetrade.io/owner: {{ .Values.bfl.username }} + applications.app.bytetrade.io/author: bytetrade.io + annotations: + applications.app.bytetrade.io/icon: https://docs-dev.olares.com/icon.png + applications.app.bytetrade.io/title: Desktop-dev + applications.app.bytetrade.io/version: '0.0.1' + + # Configuration of entrances here should be consistent with the configuration in OlaresManifest.yaml. + applications.app.bytetrade.io/entrances: '[{"name":"desktop-frontend-dev", "host":"desktop-svc-dev", "port":80,"title":"Desktop-dev"}]' + ``` + +4. Modify service + + ```Yaml + --- + apiVersion: v1 + kind: Service + metadata: + name: desktop-svc-dev + namespace: user-space-{{ .Values.bfl.username }} + spec: + selector: + app: desktop-dev + ports: + - protocol: TCP + port: 80 + targetPort: 8080 # Please note, the port of the Node.js dev container is 8080. please switch to this port. + ``` + +5. Modify the section of entrances in `OlaresManifest.yaml` + + ```Yaml + entrances: + - name: desktop-frontend-dev # Same with annotation in deployment + host: desktop-svc-dev # Same with the name in service + port: 80 + icon: https://file.bttcdn.com/appstore/default/defaulticon.webp + title: Desktop-dev + authLevel: private + openMethod: default + ``` + +6. Add service to provide `app-service` installation check + + ```Yaml + # provide `app-service` installation check + --- + apiVersion: v1 + kind: Service + metadata: + name: desktop-svc-dev # Same with the name in original service + namespace: {{ .Release.Namespace }} + spec: + type: ExternalName + externalName: desktop-svc-dev.user-space-{{ .Values.bfl.username }}.svc.cluster.local + ports: + - protocol: TCP + name: desktop + port: 80 + targetPort: 80 + ``` + +7. If you need to add a `local cache` or require access to the `user directory` in `JuiceFS`, you can add + + ```Yaml + volumes: + - name: appdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appData }}/desktop-dev + + - name: userdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.userData }}/desktop-dev + + - name: appcache + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appCache }}/desktop-dev + ``` + +--- + +:::details Example of a complete `deployment.yaml` file + +```YAML +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: desktop-dev + namespace: user-space-{{ .Values.bfl.username }} + labels: + app: desktop-dev + applications.app.bytetrade.io/name: desktop-dev + applications.app.bytetrade.io/owner: {{ .Values.bfl.username }} + applications.app.bytetrade.io/author: bytetrade.io + annotations: + applications.app.bytetrade.io/icon: https://docs-dev.olares.com/icon.png + applications.app.bytetrade.io/title: Desktop-dev + applications.app.bytetrade.io/version: '0.0.1' + applications.app.bytetrade.io/entrances: '[{"name":"desktop-frontend-dev", "host":"desktop-svc-dev", "port":80,"title":"Desktop-dev"}]' +spec: + replicas: 1 + selector: + matchLabels: + app: desktop-dev + template: + metadata: + labels: + app: desktop-dev + spec: + volumes: + - name: olares-sidecar-config + configMap: + name: sidecar-configs + items: + - key: envoy.yaml + path: envoy.yaml + - name: appdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appData }}/desktop-dev + + - name: userdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.userData }}/desktop-dev + + - name: appcache + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appCache }}/desktop-dev + + initContainers: + - name: olares-sidecar-init + image: openservicemesh/init:v1.2.3 + imagePullPolicy: IfNotPresent + securityContext: + privileged: true + capabilities: + add: + - NET_ADMIN + runAsNonRoot: false + runAsUser: 0 + command: + - /bin/sh + - -c + - | + iptables-restore --noflush <=0.1.0' + type: system + appScope: + clusterScoped: false + appRef: [] +``` +::: \ No newline at end of file diff --git a/docs/developer/contribute/system-app/other.md b/docs/developer/contribute/system-app/other.md new file mode 100644 index 000000000..3c291408f --- /dev/null +++ b/docs/developer/contribute/system-app/other.md @@ -0,0 +1,127 @@ +# Other + +## Change Provider Registry + +If you need to connect the `provider` of the original system application to your development environment, you can manually change the address of the `ProviderRegistry`. In the **'CRDs'** page of the control hub, locate `sys.bytetrade.io` and then find the `ProviderRegistry`. + +![image](/images/developer/develop/contribute/system-app/other/provider_registry.jpg) + +In the list, navigate to the app you wish to replace (in this case, **desktop-notification**). Click on the **'...'** button on the right and select **'Edit YAML'**. Modify the `endpoint` in the **YAML** file and direct it towards the service address of your **developing app**. Click **'OK'** to save and apply the changes. + +![image](/images/developer/develop/contribute/system-app/other/edit_yaml.jpg) + + +## Vite configuration + +If your frontend project uses **Vite**, you need to add an **HMR** configuration. In development mode, **Vite** initiates a **WebSocket** to receive code reload notifications from the server. The default **WebSocket** port matches the server's startup port. However, if the development app uses an **Nginx proxy** it will operate on the default port 443. Therefore, some modifications are required. + +If you are using **Quasar** + **Vite**, add the following in the `quasar.config.js`: + +```js +extendViteConf(viteConf) { + viteConf.server.hmr = {clientPort: 443}; +}, +``` +If it is a standalone **Vite** project, modify `vite.config.js` as: +```js +export default defineConfig({ + server: { + hmr: { + clientPort: 443, + }, + }, +}); +``` + +## Use System Database + +You can add **system databases** by adding `MiddlewareRequest` in the `deployment.yaml`. +Using the **Postgres** in Dify as an example: +```Yaml +apiVersion: apr.bytetrade.io/v1alpha1 +kind: MiddlewareRequest +metadata: + name: dify-pg + namespace: os-system +spec: + app: dify + appNamespace: os-system + middleware: postgres + postgreSQL: + user: dify_os_system + password: + valueFrom: + secretKeyRef: + key: pg_password + name: dify-secrets + databases: + - name: dify +``` + +You need to set a `secret` of password for adding a `MiddlewareRequest`, + +```Yaml +apiVersion: v1 +kind: Secret +metadata: + name: dify-secrets + namespace: {{ .Release.Namespace }} +type: Opaque +data: + pg_password: {{ $pg_password }} # Password can be randomly generated, then Base64 encoded +``` + +Configure the following in the pod where you want to use the database. + +```Yaml +env: + - name: DB_USERNAME + value: dify_user_space_{{ .Values.bfl.name }} # Please note, you need to add a namespace suffix when use the username configured in the MiddlewareRequest above. For username in Postgres, you also need to replace - with _ + - name: DB_PASSWORD + value: {{ $pg_password | b64dec }} # The decoded password configured above + - name: DB_HOST + value: citus-master-svc.user-system-{{ .Values.bfl.username }} # HOST address, + # For Redis: redis-cluster-proxy.user-system-{{ .Values.bfl.username }} + # For Mongo: mongo-cluster-mongos.user-system-{{ .Values.bfl.username }} + - name: DB_PORT + value: '5432' + # For Redis: 6379 + # For Mongo: 27017 + - name: DB_DATABASE + value: os_system_dify # Please note, you need to add a namespace suffix when use the database name configured in the MiddlewareRequest above. For username in Postgres, you also need to replace - with _ +``` + +You can also concatenate the `dsn` link: + +```Yaml +postgres://dify_{{ .Values.bfl.username }}:{{ $pg_password_data }}@citus-master-svc.user-system-{{ .Values.bfl.username }}/user_space_{{ .Values.bfl.username }}_dify?sslmode=disable + +mongodb://dify-{{ .Values.bfl.username }}:{{ $mongo_password_data }}@mongo-cluster-mongos.user-system-{{ .Values.bfl.username }}:27017/{{ .Release.Namespace }}_dify + +redis://:{{ $redis_password | b64dec }}@redis-cluster-proxy.user-system-{{ .Values.bfl.username }}:6379/0 # Please note, Since the system uses Redis Cluster, the database name must set to '0'. +``` + +To register a provider, you need to add a `ProviderRegistry` in the `deployment.yaml` file. + +```Yaml +apiVersion: sys.bytetrade.io/v1alpha1 +kind: ProviderRegistry +metadata: + name: desktop-provider-dev # The name cannot be duplicated with the existing one. + namespace: user-system-{{ .Values.bfl.username }} +spec: + + dataType: config-dev # The dataTypes cannot be duplicated with an existing one. If you want to replace an existing dataType, you need to delete it first. + deployment: desktop-dev + description: Set Desktop Config + endpoint: desktop-svc-dev.{{ .Release.Namespace }} # The address of the provider, pointing to your developing app + group: service.desktop + kind: provider + namespace: {{ .Release.Namespace }} + opApis: + - name: Update + uri: /server/updateDesktopConfig + version: v1 +status: + state: active +``` diff --git a/docs/developer/contribute/system-app/overview.md b/docs/developer/contribute/system-app/overview.md new file mode 100644 index 000000000..da87e2b74 --- /dev/null +++ b/docs/developer/contribute/system-app/overview.md @@ -0,0 +1,19 @@ + +# Develop System Application for Olares + +::: tip Prerequisites Knowledge +- Debugging third-party applications with **DevBox** +- Developing applications with **DevBox** +- Understanding the architecture and mechanisms of **Olares** +::: + +After a year and a half of work, the Olares team now uses **DevBox** for developing system applications. + +We will show you how to debug issues in the frontend code of **Desktop** using **DevBox**. +1. Create an application in DevBox +2. Configure [deployment.yaml](./deployment) +3. Configure [OlaresManifest.yaml](./olares-manifest) +4. Install the application +5. Configure [nginx.conf](./install) + +There are also some [other](./other) aspects to consider in development. \ No newline at end of file diff --git a/docs/developer/develop/advanced/account.md b/docs/developer/develop/advanced/account.md new file mode 100644 index 000000000..5abc9b44c --- /dev/null +++ b/docs/developer/develop/advanced/account.md @@ -0,0 +1,80 @@ +# Account + +If an app in Olares wants to use the system user as the app's user, it can obtain the user information by defining a `SysEventRegistry` in application chart to receive system user event callbacks. + +- Define `user create` callback + + ```yaml + apiVersion: apr.bytetrade.io/v1alpha1 + kind: SysEventRegistry + metadata: + name: user-create-cb + namespace: "{{ .Release.Namespace }}" + spec: + type: subscriber + event: user.create + callback: http://app-svc.{{ .Release.Namespace }}:8080/callback/create + ``` + Response data + ```http + POST /callback/create HTTP/1.1 + Content-Type: application/json + + { + "name": "user1", + "role": "workspace-manager", + "email": "user1@xxx.com" + } + ``` + +- Define `user delete` callback + + ```yaml + apiVersion: apr.bytetrade.io/v1alpha1 + kind: SysEventRegistry + metadata: + name: user-delete-cb + namespace: "{{ .Release.Namespace }}" + spec: + type: subscriber + event: user.delete + callback: http://app-svc.{{ .Release.Namespace }}:8080/callback/delete + ``` + Response data + ```http + POST /callback/delete HTTP/1.1 + Content-Type: application/json + + { + "name": "user1", + "email": "user1@xxx.com" + } + ``` + +- Define `user active` callback + + ```yaml + apiVersion: apr.bytetrade.io/v1alpha1 + kind: SysEventRegistry + metadata: + name: user-active-cb + namespace: "{{ .Release.Namespace }}" + spec: + type: subscriber + event: user.active + callback: http://app-svc.{{ .Release.Namespace }}:8080/callback/activate + ``` + Response data + ```http + POST /callback/activate HTTP/1.1 + Content-Type: application/json + + { + "name": "user1", + "email": "user1@xxx.com" + } + ``` + +:::tip +To receive system callback notifications, the app must define a service and register it. For instance, the `app-svc` mentioned above. +::: \ No newline at end of file diff --git a/docs/developer/develop/advanced/ai.md b/docs/developer/develop/advanced/ai.md new file mode 100644 index 000000000..d9d829947 --- /dev/null +++ b/docs/developer/develop/advanced/ai.md @@ -0,0 +1,547 @@ +--- +outline: [2, 3] +--- + +# AI + +## API Prefix + +`agent.{username}.olares.com/api/controllers/console/api` + +## Basic Application Management API +### Get App List +- **Request** + - **URL**: `/apps` + - **Method**: `GET` + - **URL Parameters**: `/apps?page=1&limit=30&name=Ashia` + :::tip + Most of the APIs listed in this document require the `app_id`, which can be obtained from the response of this API. + ::: + +### Create App +- **Request** + - **URL**: `/apps` + - **Method**: `POST` + - **Body Example**: + ```json + { + "name": "TEST", + "icon": "🤖", + "icon_background": "#FFEAD5", + "mode": "agent-chat", + "description": "JUST A TEST" + } + ``` + +### Get App Details +- **Request** + - **URL**: `/apps/{uuid:app_id}` + - **Method**: `GET` + - **Body Example**: `null` + +### Delete App +- **Request** + - **URL**: `/apps/{uuid:app_id}` + - **Method**: `DELETE` + - **Body Example**: `null` + +### Copy App +- **Request** + - **URL**: `/apps/{uuid:app_id}/copy` + - **Method**: `POST` + - **Body Example**: + ```json + { + "name": "Ashia-2", + "icon": "🤖", + "icon_background": "#FFEAD5", + "mode": "agent-chat" + } + ``` + +### Rename App +- **Request** + - **URL**: `/apps/{uuid:app_id}/name` + - **Method**: `POST` + - **Body Example**: + ```json + { + "name": "Ashia—34" + } + ``` + +### Change App Icon +- **Request** + - **URL**: `/apps/{uuid:app_id}/icon` + - **Method**: `POST` + - **Body Example**: + ```json + { + "icon": "heavy_check_mark" + } + ``` + +### App Web Access Control +> Whether the app can be accessed from the site. +- **Request** + - **URL**: `/apps/{uuid:app_id}/site-enable` + - **Method**: `POST` + - **Body Example**: + ```json + { + "enable_site": true + } + ``` + +### App API Access Control +> Whether the app can be accessed via API. +- **Request** + - **URL**: `/apps/{uuid:app_id}/api-enable` + - **Method**: `POST` + - **Body Example**: + ```json + { + "enable_api": true + } + ``` + +## Application Function API +### Text Generation +> Execution interface for text generation APP +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-messages` + - **Method**: `POST` + - **Body Example**: + :::details + ```json + { + "inputs": { + "query": "Hello～" + }, + "model_config": { + "pre_prompt": "{{query}}", + "prompt_type": "simple", + "chat_prompt_config": {}, + "completion_prompt_config": {}, + "user_input_form": [ + { + "paragraph": { + "label": "Query", + "variable": "query", + "required": true, + "default": "" + } + } + ], + "dataset_query_variable": "", + "opening_statement": null, + "suggested_questions_after_answer": { + "enabled": false + }, + "speech_to_text": { + "enabled": false + }, + "retriever_resource": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false, + "type": "", + "configs": [] + }, + "more_like_this": { + "enabled": false + }, + "model": { + "provider": "openai_api_compatible", + "name": "nitro", + "mode": "chat", + "completion_params": { + "temperature": 0.7, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 0, + "max_tokens": 512 + } + }, + "text_to_speech": { + "enabled": false, + "voice": "", + "language": "" + }, + "agent_mode": { + "enabled": false, + "tools": [] + }, + "dataset_configs": { + "retrieval_model": "single", + "datasets": { + "datasets": [] + } + }, + "file_upload": { + "image": { + "enabled": false, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + } + }, + "response_mode": "streaming" + } + ``` + ::: + +### Stop Text Generation +> Interruption interface for text generation APP +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-messages/{string:task_id}/stop` + - **Method**: `POST` + - **Body Example**: `null` + :::tip + The `task_id` required in this API can be obtained from the response (streaming) of the [Text Generation](#text-generation) API. + ::: + +### Chat +> Execution interface for chat APP +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages` + - **Method**: `POST` + - **Body Example**: + :::details + ```json + { + "response_mode": "streaming", + "conversation_id": "", + "query": "Hello～", + "inputs": {}, + "model_config": { + "pre_prompt": "", + "prompt_type": "simple", + "chat_prompt_config": {}, + "completion_prompt_config": {}, + "user_input_form": [], + "dataset_query_variable": "", + "opening_statement": "", + "more_like_this": { + "enabled": false + }, + "suggested_questions": [], + "suggested_questions_after_answer": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "", + "language": "" + }, + "speech_to_text": { + "enabled": false + }, + "retriever_resource": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "agent_mode": { + "max_iteration": 5, + "enabled": true, + "tools": [], + "strategy": "react" + }, + "dataset_configs": { + "retrieval_model": "single", + "datasets": { + "datasets": [] + } + }, + "file_upload": { + "image": { + "enabled": false, + "number_limits": 2, + "detail": "low", + "transfer_methods": [ + "local_file" + ] + } + }, + "annotation_reply": { + "enabled": false + }, + "supportAnnotation": true, + "appId": "2c937aae-f4f2-4cf9-b6e2-f2f2756858c0", + "supportCitationHitInfo": true, + "model": { + "provider": "openai_api_compatible", + "name": "nitro", + "mode": "chat", + "completion_params": { + "temperature": 2, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 0, + "max_tokens": 512, + "stop": [] + } + } + } + } + ``` + ::: + + +### Stop Chat +> Interruption interface for chat APP +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages/{string:task_id}/stop` + - **Method**: `POST` + - **Body Example**: `null` + :::tip + The `task_id` required in this API can be obtained from the response (streaming) of the [Chat](#chat) API. + ::: + +### Get Conversations List (Text Generation) +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-conversations` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/completion-conversations?page=1&limit=30` + :::tip + the Conversations (Text Generation) APIs listed below require the `conversation_id`, which can be obtained from the response of this API. + ::: + +### Get Conversations Details (Text Generation) +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-conversations/{uuid:conversation_id}` + - **Method**: `GET` + - **Body Example**: `null` + :::tip + The Conversations (Text Generation) APIs listed below require the `message_id`, which can be obtained from the response of this API. + ::: + +### Delete Conversations Details (Text Generation) +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-conversations/{uuid:conversation_id}` + - **Method**: `DELETE` + - **Body Example**: `null` + +### Get Conversations List (Chat) +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-conversations` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/chat-conversations?page=1&limit=30` + :::tip + the Conversations (Chat) APIs listed below require the `conversation_id`, which can be obtained from the response of this API. + ::: + +### Get Conversations Details (Chat) +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-conversations/{uuid:conversation_id}` + - **Method**: `GET` + - **Body Example**: `null` + :::tip + The Conversations (Chat) APIs listed below require the `message_id`, which can be obtained from the response of this API. + ::: + +### Delete Conversations Details (Chat) +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-conversations/{uuid:conversation_id}` + - **Method**: `DELETE` + - **Body Example**: `null` + +### Get Suggested Questions (Chat) +> In a chat APP, get the suggested questions that can be asked after the AI gives a response +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages/{uuid:message_id}/suggested-questions` + - **Method**: `GET` + - **Body Example**: `null` + +### Get Message List (Chat) +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/chat-messages?conversation_id={conversation_id}` + +### Message Feedback +> Give like or dislike feedback to the message from the APP +- **Request** + - **URL**: `/apps/{uuid:app_id}/feedbacks` + - **Method**: `POST` + - **Body Example**: + ```json + { + "rating": "like" // "like" | "dislike" | null + } + ``` + +### Message Annotation +> Give annotation to the message from the APP (Text Generation) +- **Request** + - **URL**: `/apps/{uuid:app_id}/annotations` + - **Method**: `POST` + - **Body Example**: + ```json + { + "message_id": "2b79fdad-e513-45ef-9532-8de5086cb81c", + "question": "query:How are you?", + "answer": "some answer messages" + } + ``` + +### Count Annotation +> Get the current number of annotations of the APP's message +- **Request** + - **URL**: `/apps/{uuid:app_id}/annotations/count` + - **Method**: `GET` + - **Body Example**: `null` + + +### Get Message Details (Chat) +- **Request** + - **URL**: `/apps/{uuid:app_id}/messages/{uuid:message_id}` + - **Method**: `GET` + - **Body Example**: `null` + +## Advanced Application Management API + +### Model Config +- **Request** + - **URL**: `/apps/{uuid:app_id}/model-config` + - **Method**: `POST` + - **Body Example**: + :::details + ```json + { + "pre_prompt": "", + "prompt_type": "simple", + "chat_prompt_config": {}, + "completion_prompt_config": {}, + "user_input_form": [], + "dataset_query_variable": "", + "opening_statement": "", + "suggested_questions": [], + "more_like_this": { + "enabled": false + }, + "suggested_questions_after_answer": { + "enabled": false + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "language": "", + "voice": "" + }, + "retriever_resource": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "agent_mode": { + "max_iteration": 5, + "enabled": true, + "strategy": "react", + "tools": [] + }, + "model": { + "provider": "openai_api_compatible", + "name": "nitro", + "mode": "chat", + "completion_params": { + "frequency_penalty": 0, + "max_tokens": 512, + "presence_penalty": 0, + "stop": [], + "temperature": 2, + "top_p": 1 + } + }, + "dataset_configs": { + "retrieval_model": "single", + "datasets": { + "datasets": [] + } + }, + "file_upload": { + "image": { + "enabled": false, + "number_limits": 2, + "detail": "low", + "transfer_methods": [ + "local_file" + ] + } + } + } + ``` + ::: + +### Change APP Basic Info +- **Request** + - **URL**: `/apps/{uuid:app_id}/site` + - **Method**: `POST` + - **Body Example**: + ```json + { + "title": "Ashias-23", + "icon": "grin", + "icon_background": "#000000", + "description": "How do you do~" + } + ``` +### Access Token Reset +> Regenerate the public access URL for the APP +- **Request** + - **URL**: `/apps/{uuid:app_id}/site/access-token-reset` + - **Method**: `POST` + - **Body Example**: `null` + +## Application Statistics API +### All Conversations +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/daily-conversations` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/daily-conversations?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### Active Users +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/daily-end-users` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/daily-end-users?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### Token Costs +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/token-costs` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/token-costs?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### Average Session Interactions +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/average-session-interactions` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/average-session-interactions?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### User Satisfaction +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/user-satisfaction-rate` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/user-satisfaction-rate?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### Average Response Time +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/average-response-time` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/average-response-time?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### Token Output Speed +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/tokens-per-second` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/tokens-per-second?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` diff --git a/docs/developer/develop/advanced/cli/olares-change-ip.md b/docs/developer/develop/advanced/cli/olares-change-ip.md new file mode 100644 index 000000000..34fe0f5fe --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-change-ip.md @@ -0,0 +1,33 @@ +# `olares change-ip` +:::warning When manually updating IP address is required +When Olares is deployed _inside_ a virtualized environment, such as macOS (via Minikube) or Windows (via WSL), a change in the host system's IP address (e.g., due to switching Wi-Fi networks) may cause Olares to become inaccessible. This happens because the NAT gateway and DNS configuration no longer match the new IP. In such cases, you need to manually update the IP address to ensure that Olares can route traffic correctly. + ::: + +## Synopsis +Change the local IP address for all Olares components. + +```bash +olares-cli olares change-ip [option] +``` + +## Options + +| Name | Shorthand | Usage | +|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares.
Defaults to `$HOME/.olares`. | +| `--distribution` | `-d` | Sets the WSL distribution name. Only applicable on Windows.
Defaults to `Ubuntu`. | +| `--help` | `-h` | Displays help information. | +| `--profile` | `-p` | Sets the Minikube profile name. Only applicable on macOS.
Defaults to `olares-0`. | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | + +## Examples +- For macOS: +```bash +# Specify the Minikube profile name and change the IP. +olares-cli olares change-ip --profile olares-0 +``` +- For Windows WSL: +```bash +# Specify the Linux distribution in WSL and change the IP. +olares-cli olares change-ip --distribution Ubuntu +``` \ No newline at end of file diff --git a/docs/developer/develop/advanced/cli/olares-cli.md b/docs/developer/develop/advanced/cli/olares-cli.md new file mode 100644 index 000000000..5670153d0 --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-cli.md @@ -0,0 +1,50 @@ +--- +outline: [2, 3] +--- +# Olares CLI + +Olares provides Olares CLI, a command-line tool for developers and system administrators to customize or troubleshoot the Olares installation process. + +The recommended [one-liner installation command](../../../../manual/get-started/install-olares.md) retrieves a shell script from https://olares.sh/ that downloads and installs Olares CLI. Once installed, the CLI orchestrates the remainder of the setup. + +In general, Olares CLI manages installation through three main phases: +1. **Download**: Olares CLI fetches the necessary components. +2. **Prepare**: Olares CLI prepares the environment for installation. +3. **Install**: Olares CLI installs the core services of Olares. + +This page explains the Olares CLI syntax and describes the command operations. + +:::info Root privileges required +Most `olares-cli` commands require root privileges. Use the root user or prepend commands with `sudo`. +::: + +## Syntax +The Olares CLI uses the following syntax: + +> `olares-cli command [subcommand] [option]` + +where +- `command`: Specifies the main operation you want to perform. For example, `olares download`. +- `subcommand`: Further specifies the task of `command`. For example, `wizard` or `component`. +- `option`: Optional arguments that modify the behavior of the `command`. Options include flags and options with arguments. + +Olares CLI allows you to temporarily override certain Olares default settings. Each option applies only to the command in which it is used. + +For example, if you use the `--base-dir` option with `olares-cli olares download wizard`, it will only affect the wizard downloading process and will not change the base directory for other commands, such as during the "install" phase. + +To get detailed help for any command, run `olares-cli help`. + +## Available CLI commands + +| Operation | Syntax | Description | +|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| `olares info` | `olares-cli olares info [option]` | Displays general information about the downloaded Olares OS. | +| `olares download` | `olares-cli olares download [subcommand] [option]` | Downloads specific resources. | +| `olares prepare` | `olares-cli olares prepare [option]` | Prepares the environment for the installation process, including setting up essential services and configurations of Olares. | +| `olares install` | `olares-cli olares install [option]` | Deploys system-level and user-level components of Olares. | +| `olares change-ip` | `olares-cli olares change-ip [option]` | Changes the IP address of the Olares OS. | +| `olares release` | `olares-cli olares release [option]` | Packages Olares installation resources for distribution or deployment. | +| `olares uninstall` | `olares-cli olares uninstall [option]` | Uninstalls Olares completely, or roll back the installation to a specific phase. | + + + diff --git a/docs/developer/develop/advanced/cli/olares-download.md b/docs/developer/develop/advanced/cli/olares-download.md new file mode 100644 index 000000000..fc69419da --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-download.md @@ -0,0 +1,46 @@ +# `olares download` + +## Synopsis +The `olares download` command downloads the necessary packages and components required to install Olares on your local machine. It supports downloading components, checking the status of installation packages, and fetching the manifest file. + +```bash +olares-cli olares download [subcommand] [option] +``` + +## Subcommands + +| Name | Shorthand | Usage | Example | +|-------------|-----------|-------------------------------------------------------|----------------------------------------| +| `check` | | Checks the status of the Olares installation package. | `olares-cli olares download check` | +| `component` | `c` | Downloads Olares components. | `olares-cli olares download component` | +| `wizard` | `w` | Downloads the manifest file. | `olares-cli olares download wizard` | + +## Options + +| Name | Shorthand | Usage | +|----------------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares.
Defaults to `$HOME/.olares`. | +| `--download-cdn-url` | | Sets the CDN accelerated download URL in the format `https://example.cdn.com`.
If not provided, the default URL will be used. | +| `--help` | `-h` | Displays help information. | +| `--kube` | | Specifies the Kubernetes type.
Supported types are `k3s` (default) and `k8s`. | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | + +## Examples +```bash +# Specifies the base directory where all downloaded components will be stored. +olares-cli olares download component -b /custom/path + +# Specifies a CDN-accelerated URL for downloading Olares components. +olares-cli olares download component --download-cdn-url https://my.cdn.com + +# Specifies the Kubernetes type for the installation. +olares-cli olares download component --kube k8s + +# Sets the path to the package manifest file. +olares-cli olares download component --manifest /custom/path/manifest.json + +# Specifies the version of Olares packages and components to download. +olares-cli olares download component -v 1.11.0 +``` + + diff --git a/docs/developer/develop/advanced/cli/olares-info.md b/docs/developer/develop/advanced/cli/olares-info.md new file mode 100644 index 000000000..d2a1e1c08 --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-info.md @@ -0,0 +1,14 @@ +# `olares info` + +## Synopsis +The `olares info` command displays general information about the installed Olares version. + +```bash +olares-cli olares info +``` + +## Flags + +| Name | Shorthand | Usage | +|----------|-----------|---------------------------| +| `--help` | `-h` | Display help information. | diff --git a/docs/developer/develop/advanced/cli/olares-install.md b/docs/developer/develop/advanced/cli/olares-install.md new file mode 100644 index 000000000..aa8077500 --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-install.md @@ -0,0 +1,19 @@ +# `olares install` + +## Synopsis +The `olares install` command installs Olares on your system. It supports various options to customize the installation process, such as specifying directories, Kubernetes types, or Minikube profiles. + +```bash +olares-cli olares install [option] +``` + +## Options + +| Name | Shorthand | Usage | +|--------------|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares.
Defaults to `$HOME/.olares`. | +| `--help` | `-h` | Displays help information. | +| `--kube` | | Specifies the Kubernetes type.
Supported types are `k3s` (default) and `k8s`. | +| `--profile` | `-p` | Sets the Minikube profile name. Only applicable on macOS.
Defaults to `olares-0`. | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | + diff --git a/docs/developer/develop/advanced/cli/olares-prepare.md b/docs/developer/develop/advanced/cli/olares-prepare.md new file mode 100644 index 000000000..3f8932727 --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-prepare.md @@ -0,0 +1,25 @@ +# `olares prepare` + +## Synopsis +The `olares prepare` command sets up the environment required for Olares to function. This includes installing dependencies, importing container images, and starting the Olares daemon (`olaresd`). +```bash +olares-cli olares prepare [option] +``` + +## Options + +| Name | Shorthand | Usage | +|----------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares.
Defaults to `$HOME/.olares`. | +| `--help` | `-h` | Displays help information. | +| `--kube` | | Specifies the Kubernetes type.
Supported types are `k3s` (default) and `k8s`. | +| `--profile` | `-p` | Sets the Minikube profile name. Only applicable on macOS.
Defaults to `olares-0`. | +| `--registry-mirrors` | `-r` | Specifies Docker container registry mirrors.
Multiple mirrors should be separated by commas. | +| `--with-juicefs` | | Configures JuiceFS as the root filesystem (rootfs) for Olares workloads instead of the local disk. | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | + +## Example +```bash +# Uses JuiceFS as the root filesystem +olares-cli olares prepare --with-juicefs=true +``` \ No newline at end of file diff --git a/docs/developer/develop/advanced/cli/olares-release.md b/docs/developer/develop/advanced/cli/olares-release.md new file mode 100644 index 000000000..4d91028e0 --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-release.md @@ -0,0 +1,20 @@ +# `olares release` + +## Synopsis +Build a release version based on a local Olares repository. This command should be run in the root directory of the Olares repository. + +```bash +olares-cli olares release [option] +``` + +## Options + +| Name | Shorthand | Usage | +|----------------------------|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares.
Defaults to `$HOME/.olares`. | +| `--download-cdn-url` | | Sets the CDN URL used for downloading checksums of dependencies and images.
Defaults to `https://dc3p1870nn3cj.cloudfront.net`. | +| `--extract` | `-e` | Extracts the release to the `--base-dir` after the build. Set to `false` if only the release file itself is needed.
Defaults to `true`. | +| `--help` | `-h` | Displays help information. | +| `---ignore-missing-images` | | Ignores missing images when downloading checksums from the CDN.
Disable this only if no new images are added, as the build may fail if the image is not uploaded to the CDN yet.
Defaults to `true`. | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | + diff --git a/docs/developer/develop/advanced/cli/olares-uninstall.md b/docs/developer/develop/advanced/cli/olares-uninstall.md new file mode 100644 index 000000000..a07af7f3b --- /dev/null +++ b/docs/developer/develop/advanced/cli/olares-uninstall.md @@ -0,0 +1,19 @@ +# `olares uninstall` + +## Synopsis +Uninstall Olares from your machine. + +```bash +olares-cli olares uninstall [option] +``` + +## Options + +| Name | Shorthand | Usage | +|--------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--all` | | Uninstalls Olares completely, including dependencies installed during the "prepare" phase. | +| `--base-dir` | `-b` | Sets the base directory for Olares.
Defaults to `$HOME/.olares`. | +| `--help` | `-h` | Displays help information. | +| `--phase` | | Uninstalls Olares from a specific phase and revert to the previous one.
For example, `--phase install` removes tasks performed during the "install" phase, reverting the system to the "prepare" stage.
Defaults to `install`. | +| `--quiet` | | Enables quiet mode (suppress output).
Defaults to `false`. | +| `--version` | `-v` | Specifies the Olares version to uninstall.
Use `olares-cli olares info` to check the downloaded version first. | diff --git a/docs/developer/develop/advanced/cookie.md b/docs/developer/develop/advanced/cookie.md new file mode 100644 index 000000000..b7ee96bc9 --- /dev/null +++ b/docs/developer/develop/advanced/cookie.md @@ -0,0 +1,26 @@ +# Cookie + +**Single Sign-On (SSO)** mode is utilized for authorization and authentication across the **Olares**, including all installed apps. **SSO** authentication is non-intrusive, using cookies as the authentication credential. + +The system will set two cookies after login + +- **authelia_session** + + The content of the cookie is the session id of SSO. The scope is the user's Olares domain, `.olares.com` + +- **auth_token** + + The user authenticated authorization token. The scope is the user's Olares domain, `.olares.com` + +To prevent cookie conflicts, **no application** (whether it's a built-in system app or a third-party app) can set cookies to the user's domain. Cookies can only be set to the domain of the app. + +Every application in **Olares** operates under two domains: <`app id>..olares.com` and `.local..olares.com`. As a result, Olares incorporates a cookie-setting `rewrite` mechanism within the Olares Application Runtime. This ensures that the application automatically assigns cookies for both domains in the Set-`Cookie` field of the **HTTP response**. + +To use this feature, you just need to define it in the application chart's [OlaresManifest.yaml](../package/manifest.md#resetcookie) + +```yaml +options: + resetCookie: + enabled: true + +``` \ No newline at end of file diff --git a/docs/developer/develop/advanced/database.md b/docs/developer/develop/advanced/database.md new file mode 100644 index 000000000..18b6c0f69 --- /dev/null +++ b/docs/developer/develop/advanced/database.md @@ -0,0 +1,65 @@ +# Database + +The Olares system provides three most popular data storage cluster for all APPs, covering `RDS`, `NoSQL`, and `Cache` data storage use cases. + +## RDS + +The system has deployed **PostgreSQL** and provides two types of databases. + +- **Standalone PostgreSQL**, providing the most commonly used `RDS` database layer functions. +- **Distributed PostgreSQL** extension, powered by **Citus**. Provides the ability to horizontally scale the database. + +When setting up a **PostgreSQL** database, you can specify the type of database to be used in [OlaresManifest.yaml](../package/manifest.md#middleware). + +```yaml +middleware: +postgres: + username: postgres + databases: + - name: db + distributed: true # Whether the database is distributed in the cluster. +``` + +If you use **Citus**, **Olares** will automatically shard the database tables and perform rebalancing during the horizontal scaling of **PostgreSQL** replicas. + +## NoSQL + +The NoSQL cluster is not deployed by default in Olares, but it can be easily installed from the Market. To set up a NoSQL cluster, the administrator needs to install the [**MongoDB**](https://market.olares.com/middleware/mongodb) middleware. Once installed, the [Percona Operator for MongoDB](https://github.com/percona/percona-server-mongodb-operator) automatically manages the **MongoDB** cluster. Users can then horizontally scale **MongoDB** cluster replicas, as well as perform backup and restore operations on databases. + +You can specify detailed configuration for MongoDB in [OlaresManifest.yaml](../package/manifest.md#middleware) as follows: + +```yaml +middleware: + mongodb: + username: mongodb + databases: + - name: db0 + - name: db1 +options: + dependencies: + - name: olares + type: system + version: ">=1.6.0-0" + - name: mongodb + version: ">=6.0.0-0" + type: middleware +``` + +## Cache + +In terms of the Cache cluster, Olares uses Redis Cluster. The cluster is managed by a customized [Redis Cluster Operator](https://github.com/beclab/redis-cluster-operator) to achieve cloud nativeness. It enables us to scale replicas horizontally in a convenient and effective manner. + +To ensure **data isolation** between users and apps in the **Redis cluster**, the **Olares** system has added a **Redis cluster proxy**. It isolates data based on the `namespace`. This operation is transparent, meaning app developers typically do not need to be aware of it. + +Additionally, this proxy simplifies the process of connecting to clusters. It eliminates the need to switch from a **standalone Redis Client** to a **Redis Cluster client** in the app, thus simplifying app code modifications. + +``` +middleware: + redis: + password: password + namespace: db0 +``` + +:::info NOTE +Since Olares uses the Redis Cluster version, developers need to understand the usage restrictions of Redis Cluster in detail when using it. +::: diff --git a/docs/developer/develop/advanced/file-upload.md b/docs/developer/develop/advanced/file-upload.md new file mode 100644 index 000000000..25aabf0fc --- /dev/null +++ b/docs/developer/develop/advanced/file-upload.md @@ -0,0 +1,175 @@ +--- +outline: [2, 3] +--- + +# File Upload + +There are many situations where you might need to upload local files to your edge when using **Olares**. The `Olares Application Runtime` provides a common file-upload component to simplify this process in app development. Moreover, this file-upload component features **resumable upload**. + +## How to install + +To use this feature, simply add the following configuration to the [OlaresManifest.yaml](../package/manifest.md#upload) file in the application chart. +```yaml +upload: + fileType: + - pdf + dest: /appdata + limitedSize: 3729747942 +``` + +## Frontend API + +:::info NOTE +The limit for a single upload is 10MB. If the file is larger than 10MB, you must upload using the resumable upload API. +::: + + +### Upload + +This interface is used to upload files to the server and get the file id and status. +:::details Example +**Request** +```sh +curl --location 'http://host:40030/upload/' \ +--form 'storage_path="./testupload/"' \ +--form 'file_relative_path="1.csv"' \ +--form 'file_type="csv"' \ +--form 'file_size="1937"' +``` +**Response** +```json +{ + "code": 0, + "message": "success", + "data": { + "id": "b0b76f02bdb8ee3269602c983c4a2aeb", + "offset": 0, + "file_relative_path": "1.csv", + "file_type": "csv", + "file_size": 1937, + "storage_path": "./testupload/" + } +} +``` +::: + +- **Request** + + - **URL**: `/upload/` + + - **Method**: `POST` + + - **Body**: + ``` json + "mode": "formdata", //The request body type must set to multipart/form-data + "body parameters": { + "storage_path": string, //required, the storage path for the file on the server. Ensure that this folder exists. + "file_relative_path": string, //required, the location of file relative to the storage_path, it must include the filename. If it is a floder, end with '/' + "file_type": string, //required, File type + "file_size": integer, //required, File size + } + ``` +- **Success Response** + + The response body contains the following content, formatted in JSON. + - **Status Code** : `200 OK` + ```json + "code": integer, // Response code, 0 means success, non-zero means failure. + "message": string, // Response message, return "success" upon success, and the corresponding error message upon failure. + "data":{ //Response data. Upon success, it includes the following fields (these contents is absent when uploading a folder): + "id": string, // Unique identifier of the file + "offset": integer, //The offset of the file uploaded + "file_relative_path": string, + "file_type": string, + "file_size": integer, + "storage_path": string + } + ``` + +- **Error Response** + - **Status Code** : `400 Bad Request` + > The request is invalid due to illegal or missing parameters. + - **Status Code** : `500 Internal Server Error` + > An internal server error has occurred, which prevented the request from being fulfilled. This could be due to reasons such as failure to create a folder or save file information. + +### Resumable Upload + +This interface is used to continue uploading the remaining part of the file. +:::details Example +**Request** +```sh +curl --location --request PATCH 'http://host:40030/upload/b0b76f02bdb8ee3269602c983c4a2aeb' \ +--form 'file=@"/Users/yangtao/Downloads/1.csv"' \ +--form 'upload_offset="0"' +``` +**Response** +```json +{ + "code": 0, + "message": "File uploaded successfully", + "data": { + "id": "b0b76f02bdb8ee3269602c983c4a2aeb", + "offset": 1937, + "file_name": "1.csv", + "file_type": "csv", + "file_size": 1937, + "storage_path": "./testupload" + } +} +{ + "code": 0, + "message": "Continue uploading", + "data": { + "id": "e3133b0f838124ff3ebcc9cb14774f26", + "offset": 1048576, + "file_name": "1.pdf", + "file_type": ".pdf", + "file_size": 10296258, + "storage_path": "./testupload" + } +} +``` +::: + +- **Request** + + - **URL**: `http://host:40030/upload/{uid}` + + - **Method**: `PATCH` + + - **Body**: + ``` json + "mode": "formdata", //The request body type must set to multipart/form-data + "body parameters": { + "file": string, //required. The file to be uploaded. Please upload the file in multipart/form-data format. + "upload_offset": integer, //required. The offset refers to the size of the file that has already been uploaded. + } + "url parameters": { + "uid": string, //required. This is the unique identifier of the file. You can obtain it from the response data of the Upload API. + } + ``` +- **Success Response** + + The response body contains the following content, formatted in JSON. + - **Status Code** : `200 OK` + ```json + "code": integer, // Response code, 0 means success, non-zero means failure. + "message": string, // Response message, return "File uploaded successfully" upon success, and the corresponding error message upon failure. + "data":{ //Response data. Upon success, it includes the following fields + "id": string, // Unique identifier of the file + "offset": integer, //The offset of the file uploaded + "file_relative_path": string, + "file_type": string, + "file_size": integer, + "storage_path": string + } + ``` + +- **Error Response** + - **Status Code** : `400 Bad Request` + > The request is invalid due to illegal or missing parameters. + ```json + { "code": 1, "message": "Invalid upload ID" } + ``` + - **Status Code** : `500 Internal Server Error` + > An internal server error has occurred, which prevented the request from being fulfilled. This could be due to reasons such as failure to create a folder, save file information, or move file. \ No newline at end of file diff --git a/docs/developer/develop/advanced/frontend.md b/docs/developer/develop/advanced/frontend.md new file mode 100644 index 000000000..fce2e39cb --- /dev/null +++ b/docs/developer/develop/advanced/frontend.md @@ -0,0 +1,9 @@ +# Frontend + +## 视觉规范 + +https://w8wvyn24o5.feishu.cn/wiki/Im1nwwPCRiIcGCkBy8qc1vNknVd + +## core 库 + +## UI 库 diff --git a/docs/developer/develop/advanced/image-6.png b/docs/developer/develop/advanced/image-6.png new file mode 100644 index 000000000..e09d75e05 Binary files /dev/null and b/docs/developer/develop/advanced/image-6.png differ diff --git a/docs/developer/develop/advanced/images/restore.jpg b/docs/developer/develop/advanced/images/restore.jpg new file mode 100644 index 000000000..84731a58a Binary files /dev/null and b/docs/developer/develop/advanced/images/restore.jpg differ diff --git a/docs/developer/develop/advanced/index.md b/docs/developer/develop/advanced/index.md new file mode 100644 index 000000000..e4a2b6471 --- /dev/null +++ b/docs/developer/develop/advanced/index.md @@ -0,0 +1,14 @@ +# Advanced + +1. [Olares CLI](cli/olares-cli.md) +2. [Olares Info](./terminus-info) +3. [Service Provider](./provider.md) +4. [AI](./ai.md) +5. [Cookie](./cookie.md) +6. [Database](./database.md) +7. [Account](./account.md) +8. [Market](./market.md) +9. [Websocket](./websocket.md) +10. [Files Upload](./file-upload.md) +11. [Secret](./secret.md) +12. [Kubesphere](./kubesphere.md) diff --git a/docs/developer/develop/advanced/kubesphere.md b/docs/developer/develop/advanced/kubesphere.md new file mode 100644 index 000000000..04a392ba5 --- /dev/null +++ b/docs/developer/develop/advanced/kubesphere.md @@ -0,0 +1,14 @@ +# Kubesphere + +Olares has integrated many advanced features of Kubesphere like the multi-user system and cluster data monitoring. To install the official console tool from **Kubesphere**, download and install it from the **Olares** code repository. + +```sh +curl -LO https://github.com/Above-Os/terminus-os/raw/main/third-party/ks-console/ks-console-v3.3.0.tgz + +# The username is your Olares ID +sudo helm install console ./ks-console-v3.3.0.tgz \ + -n user-space- \ + --set username= +``` + +After you install it, refresh your desktop. You'll then see the Console icon in Olares. Open Console and log in with your Olares ID and password. diff --git a/docs/developer/develop/advanced/market.md b/docs/developer/develop/advanced/market.md new file mode 100644 index 000000000..1427371d9 --- /dev/null +++ b/docs/developer/develop/advanced/market.md @@ -0,0 +1,79 @@ +# Market + +To install or uninstall apps in developing applications (for example, third-party Market extensions), developers can use the `install` and `uninstall` API provided by the **Market**. + +For how to define and call provider, please refer to [Service Provider](./provider.md) + +**Provider from Market** + +| Group | version | dataType | ops | +| ---------------- | ------- | -------- | ----------------------------- | +| service.appstore | v1 | app | `InstallDevApp`
`UninstallDevApp` | + +## Install +- **Request** + - **URL**:
`http://$OS_SYSTEM_SERVER/system-server/v1alpha1/app/service.appstore/v1/InstallDevApp` + + - **Method**: `POST` + + - **Header** + ```http + X-Authorization: token # auth_token in cookie + X-Access-Token: access_token # access token get from authorization Provider + ``` + + - **Body** (Golang struct as an example) + ```go + type InstallOptions struct { + App string `json:"appName"` //required + RepoUrl string `json:"repoUrl"` //required + CfgUrl string `json:"cfgUrl"` //optional + Version string `json:"version"` //required when upgrading + Source string `json:"source"` //required + } + ``` + +- **Success Responses** + ```go + type InstallationResponse struct { + Code int `json:"code"` + Msg string `json:"message,omitempty"` + Data InstallationResponseData `json:"data"` + } + + type InstallationResponseData struct { + UID string `json:"uid"` + } + ``` + +## Uninstall +- **Request** + - **URL**:
`http://$OS_SYSTEM_SERVER/system-server/v1alpha1/app/service.appstore/v1/UninstallDevApp` + + - **Method**: `POST` + + - **Header** + ```http + X-Authorization: token # auth_token in cookie + X-Access-Token: access_token # access token get from authorization Provider + ``` + + - **Body** (Golang struct as an example) + ```go + type UninstallData struct { + Name string `json:"name"` //required + } + ``` + +- **Success Responses** + ```go + type InstallationResponse struct { + Code int `json:"code"` + Msg string `json:"message,omitempty"` + Data InstallationResponseData `json:"data"` + } + + type InstallationResponseData struct { + UID string `json:"uid"` + } + ``` \ No newline at end of file diff --git a/docs/developer/develop/advanced/notification.md b/docs/developer/develop/advanced/notification.md new file mode 100644 index 000000000..3217eedf2 --- /dev/null +++ b/docs/developer/develop/advanced/notification.md @@ -0,0 +1,4 @@ +# Notification + +https://w8wvyn24o5.feishu.cn/wiki/SDLsw7KTAiohe5kmYM4cyNeCnCd +https://w8wvyn24o5.feishu.cn/wiki/E8RzwY3NAiRT8UkwYxQc9Hndnbf diff --git a/docs/developer/develop/advanced/provider.md b/docs/developer/develop/advanced/provider.md new file mode 100644 index 000000000..191231105 --- /dev/null +++ b/docs/developer/develop/advanced/provider.md @@ -0,0 +1,117 @@ +# Service Provider + +App developers can define the `ProviderRegistry` in the application chart or request permission to call other providers. + +## Define Provider + +```yaml +apiVersion: sys.bytetrade.io/v1alpha1 +kind: ProviderRegistry +metadata: + # Provider name. A namespace is required to prevent duplication. + name: provider-{{ .Release.Namespace }} + + # provider registry needs to be installed under user-system + namespace: user-system-{{ .Values.bfl.username}} +spec: + version: v2 #The latest version is v2, but the system remains compatible with v1. + + # dataType of provider, it is recommended to add app name to prevent duplication. + dataType: legacy_{{ .Release.Name }} + deployment: {{ .Release.Name }} + description: {{ .Release.Name }} legacy api v2 + + # accessible service from the provider. Usually it is .: + endpoint: {{ .Release.Name }}-svc.{{ .Release.Namespace }}:1234 + + # group of the provider; it is recommended to add the app name to prevent duplication. + group: api.{{ .Release.Name }} + kind: provider + namespace: "{{ .Release.Namespace }}" + opApis: + # name of the provided API + - name: AppApi + # URL of the API + uri: /api +status: + state: active +``` + +## Request Permission to Call Provider + +You can configure it in the [OlaresManifest.yaml](../package/manifest.md#sysdata) as follows: + +```Yaml +sysData: +- appName: providerapp # The appname of the api provider. Required for ProviderRegistry v2. + port: 8888 # The port of the provider service + + # The default domain of provider is -svc.-:, if the service name and app namespace is not in default format, you can specify it in following field + svc: app-svc # Name of the service. Optional for ProviderRegistry v2. + namespace: ns # Namespace of the app. Optional for ProviderRegistry v2. + + version: v2 # version of the ProviderRegistry + dataType: legacy_{{ .Release.Name }} # dataType defined in ProviderRegistry + group: api.{{ .Release.Name }} # group defined in ProviderRegistry + ops: + - AppApi # name of opApis defined in ProviderRegistry +``` + +Once configured, you can add the `access key` and `access secret` to the templates in the application chart. They will be injected during installation for authorized usage. + +```yaml +env: + - name: OS_SYSTEM_SERVER + value: system-server.user-system-{{ .Values.bfl.username }} + - name: OS_APP_SECRET + + # The appname is defined in the application chart + value: "{{ .Values.os..appSecret }}" + - name: OS_APP_KEY + value: "{{ .Values.os..appKey }}" +``` + +You can use these three environment variables in the code to call the **Provider**. Take `curl` as an example: + +1. Get the `access token`, which has a valid duration of 5 minutes. Token encryption algorithm: bcrypt(`app key` `timestamp` `app secret`), default cost 10. + + ```sh + now=$(date +%s) + token=$(htpasswd -nbBC 10 USER "${OS_APP_KEY}${now}${OS_APP_SECRET}"|awk -F":" '{print $2}') + + curl -X POST http://${OS_SYSTEM_SERVER}/permission/v1alpha1/access -H "content-type: application/json" \ + -d "{ \ + \"app_key\": \"${OS_APP_KEY}\", \ + \"timestamp\": ${now}, \ + \"token\": \"${token}\", \ + \"perm\": { \ + \"group\": \"service.bfl\", \ + \"dataType\": \"app\", \ + \"version\": \"v1\", \ + \"ops\": [ \ + \"InstallDevApp\" \ + ] \ + } \ + }' + ``` + +2. You will receive a response like: + ```json + { + "code": 0, + "message": "success", + "data": { + "access_token": "JDJ5JDEwJE5Wbk9vbFpoLjJlSGxhUUpRY1IwRmVZVjFBWmUxUi5LOXNuQWJmVjRnN29xNWVVaFhPWmV5" + } + } + ``` + +3. You can then use the token to call the provider's API + + ```sh + # API URL format http://${OS_SYSTEM_SERVER}/system-server/v1alpha1//// + curl http://${OS_SYSTEM_SERVER}/system-server/v1alpha1/app/service.bfl/v1/InstallDevApp \ + -H "content-type: application/json" \ + -H "X-Access-Token: ${access_token}" \ + -d '{"data":"post to provider"}' + ``` diff --git a/docs/developer/develop/advanced/rss.md b/docs/developer/develop/advanced/rss.md new file mode 100644 index 000000000..b83bcc12c --- /dev/null +++ b/docs/developer/develop/advanced/rss.md @@ -0,0 +1 @@ +# RSS diff --git a/docs/developer/develop/advanced/secret.md b/docs/developer/develop/advanced/secret.md new file mode 100644 index 000000000..2635b3447 --- /dev/null +++ b/docs/developer/develop/advanced/secret.md @@ -0,0 +1,132 @@ +--- +outline: [2, 3] +--- + +# Secret + +In an app, it's often necessary to save some important user information, such as `passwords` and `Access Tokens` for external systems. Olares provides a unified Vault, based on Infisical, to securely store various keys. + +To retrieve this information, the app only needs a simple application for API access permission. This can be done by adding a `sysData` permission to the [OlaresManifest.yaml](../package/manifest.md#sysdata) in the application chart. + +```yaml +permission: + sysData: + - dataType: secret + group: secret.infisical + version: v1 + ops: + - RetrieveSecret?workspace=your-app # Each app should define its own workspace + - CreateSecret?workspace=your-app + - DeleteSecret?workspace=your-app + - UpdateSecret?workspace=your-app + - ListSecret?workspace=your-app +``` + +## Call API + +You can call the API in the same way you would request other providers. Use the full name of ops (including the workspace parameter) as the URI. + +Please include this **header** in all requests. +```http +X-Authorization: token # auth_token in cookie +``` + +### RetrieveSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":{ + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod + } + } + ``` + +### CreateSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":"" + } + ``` + + +### DeleteSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":"" + } + ``` + + +### UpdateSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":"" + } + ``` + +### ListSecret +- **Request Body** + ```json + { + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":{ + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod + } + } + ``` \ No newline at end of file diff --git a/docs/developer/develop/advanced/terminus-info.md b/docs/developer/develop/advanced/terminus-info.md new file mode 100644 index 000000000..4d99fbf85 --- /dev/null +++ b/docs/developer/develop/advanced/terminus-info.md @@ -0,0 +1,37 @@ +# terminus-info + +terminus-info is an API without authentication. It displays publicly available system information. You can think of it as a house number sign. + +## API Call + +``` +https://.olares.com/api/terminus-info +``` + +## Data Structure + +```json +interface TerminusInfo { + terminusName: string; + wizardStatus: string; + selfhosted: boolean; + tailScaleEnable: boolean; + osVersion: string; + avatar: string; + loginBackground: string; + terminusId: string; +} +``` + +## API Field Definitions + +| Field | Description | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| terminusName | The user's Olares ID follows a format like `username@domain.com`. | +| wizardStatus | Activation status of Olares, possible statuses includes: `wait_activate_vault`, `vault_activating`, `vault_activate_failed`, `wait_activate_system`, `system_activating`, `system_activate_failed`, `wait_activate_network`, `network_activating`, `network_activate_failed`, `wait_reset_password`, `completed`. When the status displays `completed`, it indicates that the system has been successfully activated. We advise against third-party programs executing excessive business-related logic before the system is fully activated. | +| selfhosted | Whether the Olares is running on Olares Space | +| tailScaleEnable | Whether the TailScale is activated. If so, all private entrances can only be accessed through the VPN.
Note: This field does not affect whether LarePass uses local access when connecting to Olares. | +| osVersion | Olares version | +| avatar | User's Avatar | +| loginBackground | Background image of the login interface | +| olaresId | Every time the user activates Olares, a new unique ID is generated. | diff --git a/docs/developer/develop/advanced/websocket.md b/docs/developer/develop/advanced/websocket.md new file mode 100644 index 000000000..bcc4e9b2e --- /dev/null +++ b/docs/developer/develop/advanced/websocket.md @@ -0,0 +1,171 @@ +--- +outline: [2, 3] +--- + +# Websocket + +**WebSocket** is one of the most widely used technologies in modern front-end development. To simplify its use in **Olares** app development, **Olares Application Runtime (TAPR)** provides a common **WebSocket** component. + +## Client + +The Client is developed using `JavaScript/TypeScript` use the **ws** library. +The application server provides the WebSocket through a URL formatted as `wss://..olares.com/ws`. + +### Send Message + +An example of WebSocket messages sent from clients is outlined below (other formats are also supported): +```json +{ + "event": "...", + "data": {...} +} +``` + +### Ping + +The client should send a 'ping' message every 30 seconds to keep the WebSocket connection alive. If the WebSocket service doesn't receive a 'ping' within the time limit, it will close the connection. The data format for the 'ping' message should adhere to the following structure: +```json +{ + "event": "ping", + "data": {} +} +``` + +## App + +The **WebSocket Service** offers multiple features: +- It allows the server to communicate with clients either by broadcasting messages or responding to WebSocket messages sent by clients. +- It can be used to close a WebSocket connection for a specific user or connection ID. +- It provides the current connection list. + +Both the **App** and **WebSocket** are deployed in the same container, allowing direct access to the **WebSocket service** via `localhost`. The service uses port `40010`. + +### Broadcast Message +```json +// URL: +// Request method: POST +// body +{ +"payload": {}, // Message. +"conn_id": "", // Connection ID; used to respond to the client's single Ws request. Do not fill in connId when broadcasting to users +"users": ["", ""], // Specify users. If this field is filled in, it is a broadcast. Do not fill in connId in broadcast situation +} + +// Response example +{ +"code": 0, +"message": "success", +} +``` + +### Close WebSocket Connection of Client +```json +// URL: +// Request method: POST +// body +{ +"conns": ["", ...], // Close specified connections +"users": ["", ...], // Close all connections for specified users +} + +// Response example +{ +"code": 0, +"message": "success", +} +``` + +### Get Current Online Connection List + +```json +// URL: +// Request method: GET +// Response example +{ + "code": 0, + "message": "success", + "data": [ + { + "name": "", + "conns": [ + { + "id": "", // Connection ID + "userAgent": "" + } + ] + } + ] +} +``` + +### Forwards Client Messages to App via WebSocket + +There are three types of client messages that will be forward to App: +- Establishing a client connection +- Regular messages sent by the client +- Client disconnected, which happens when the browser closes or network issues occur. + +**Client connection** + +```json +// URL: +// Method: POST +// body + +{ + "data": {}, + "action": "open", // action + "user_name": "", + "conn_id": "1" // WebSocket Connection ID +} + +// When the app receives the "open" message, it will execute the associated processes. +``` + +**Regular messages** + +```json +// URL: +// Method: POST +// header, the original Cookie of the client will be passed to the backend application +Cookie: .... // New feature in version v1.0.3 + +// body +{ +"data": { ... }, // The original data sent by the client to WSGateway, the internal structure is {"event":"", "data": {...}} +"action": "message", // action +"user_name": "", +"conn_id": "1", // WebSocket Connection ID +} + +// After processing, the app returns the data to the client through the "Broadcast Message" API. +``` + +**Client Disconnected** +> The WebSocket service callback the App when it receives a close message +```json +// URL: +// Method: POST +// body + +{ + "data": {}, + "action": "close", // action + "user_name": "", + "conn_id": "1" // WebSocket Connection ID +} + +// When the app receives the "close" message, it will execute the associated processes. +``` + +## Deploy WebSocket Service in App + +To use this feature, simply add the `websocket configuration` to the [OlaresManifest.yaml](../package/manifest.md#websocket) file in the application chart. +```yaml +options: + websocket: + url: /ws/message + port: 8888 +``` + +**WebSocket** is a component that facilitates message forwarding between the client and the App. Consequently, the App must provide an **API** for **WebSocket** to manage `ws` messages from the client. For instance, in the example above, the APP should provide an API named `/ws/message` on port `8888`. diff --git a/docs/developer/develop/index.md b/docs/developer/develop/index.md new file mode 100644 index 000000000..fbb3d0941 --- /dev/null +++ b/docs/developer/develop/index.md @@ -0,0 +1,15 @@ +# Develop Olares application + +Developing applications on Olares is not much different from regular website development. Once you learn a few basic Olares concepts, you can start creating applications on his platform. + +- [Core Concepts of Olares](../../manual/concepts/index.md) +- [Understanding the Format of Olares Application Chart](./package/chart.md) + - [The structure of the Olares Application Chart](./package/chart.md) + - [Configuration guide and field descriptions of `OlaresManifest.yaml`](./package/manifest.md) + - [Extensions field to Helm in Olares](./package/extension.md) + +- [Exploring Our Tutorials](./tutorial/) + - [Learn about Devbox, an Olares Development Tool](./tutorial/studio) + - [Creating your first application](./tutorial/note/) +- [Exploring Advanced Concepts](./advanced/) +- [Submitting Applications to the Olares Market](./submit/) diff --git a/docs/developer/develop/package/chart.md b/docs/developer/develop/package/chart.md new file mode 100644 index 000000000..84dfd08b4 --- /dev/null +++ b/docs/developer/develop/package/chart.md @@ -0,0 +1,48 @@ +# Olares Application Chart Structure + +The Olares Application Chart is built upon the structure of **Helm Chart**, with extensions to accommodate specific **Olares** information. A standard application chart contains the following files: +``` +|-- Chart.yaml # chart metadata +|-- OlaresManifest.yaml # Olares Application configuration +|-- templates/ # chart deployment template files +| |-- deployment.yaml # APP deployment script +|-- crds/ # OPTIONAL: Custom Resource Definitions +|-- values.yaml # OPTIONAL: The default deployment parameters for this chart +|-- values.schema.json # OPTIONAL: A JSON Schema for imposing a structure on the values.yaml file +|-- README.md # OPTIONAL: A human-readable README file +``` +:::info NOTE +To make the templates directory easier to understand, you can split the deployment into several files. +::: + +- A typical application chart for `App` and `Middleware`: +``` +AppName +|-- Chart.yaml # Required: YAML file containing chart metadata +|-- OlaresManifest.yaml # Required: containing App configuration +|-- values.yaml # Required: default configuration values of the chart +|-- templates # Required: template directory, when combined with values, it can generate valid Kubernetes manifest files +| |-- NOTES.txt # Optional: plain text file containing brief usage instructions +| |-- deployment.yaml # Defines the deployment for App installation +| |-- service.yaml # Defines the Service that provides the Entrance for the App +| |-- provider.yaml # Optional: if you need to expose the Provider API +|-- LICENSE # Optional: plain text file containing the chart license +|-- README.md # Optional: readable README file +``` + +- A typical application chart for `Recommend`: + +``` +RecommendName +|-- Chart.yaml # Required: YAML file containing chart metadata +|-- OlaresManifest.yaml # Required: containing Recommend configuration +|-- values.yaml # Required: default configuration values of the chart +|-- templates # Required: template directory, when combined with values, it can generate valid Kubernetes manifest files +| |-- NOTES.txt # Optional: plain text file containing brief usage instructions +| |-- train.yaml # Defines the train process in recommend workflows +| |-- prerank.yaml # Defines the prerank process in recommend workflows +| |-- rank.yaml # Defines the rank process in recommend workflows +| |-- embedding.yaml # Defines the embedding process in recommend workflows +|-- LICENSE # Optional: plain text file containing the chart license +|-- README.md # Optional: readable README file +``` \ No newline at end of file diff --git a/docs/developer/develop/package/extension.md b/docs/developer/develop/package/extension.md new file mode 100644 index 000000000..36bf3fdf5 --- /dev/null +++ b/docs/developer/develop/package/extension.md @@ -0,0 +1,73 @@ +# Extensions field to Helm in Olares + +During installation, Olares injects extended field into the APP, using the configuration from [OlaresManifest.yaml](manifest.md). + +The information from these extended fields can be directly referenced in the template without being defined in values.yaml. If there are definitions in values.yaml with the same name, the system value will overwrite them. + + +- User Information + + | Value | Type | Description | + | -------------------- | ------ | --------------------- | + | .Values.bfl.username | String | Username of the currently installing APP | + | .Values.user.zone | String | Domain of the current user | + +- Domain Information + + | Value | Type | Description | + | -------------- | ------------------ | ---------------------------------------------------- | + | .Values.domain | Map | Define the Entry for the App, using the entrance name as the key and the URL as the value. | + +- Storage Information + | Value | Type | Description + | -------------- | ------------------ | ---------------------------------------------------- | + | .Values.userspace.appData | String | Cluster storage address available to the APP | + | .Values.userspace.appCache | String | Local node cache address available to the APP | + | .Values.userspace.userData | String | storage directory of User's data | + +- Cluster Information + | Value | Type | Description + | -------------- | ------------------ | ---------------------------------------------------- | + | .Values.cluster.arch | String | Cluster CPU architecture | + + Multi-platform (AMD64 and ARM) cluster is not supported for now. + +- Application Dependencies + | Value | Type | Description + | -------------- | ------------------ | ---------------------------------------------------- | + | .Values.deps | Map | Current address and port of the applications the APP depends on | + | .Values.svcs | Map | Other services and ports of the applications the APP depends on | + + When an application sets dependencies on another application, this will be passed through the `deps` parameter. For instance, if an application, sets a dependency on another application called **'A-Server'**, and **'A-Server'** sets the entry name as **'aserver'** with the entry host configured as **'aserver-svc'**, the value will be like: + ``` + { + "aserver_host": "aserver-svc.", + "aserver_port": 80 + } + ``` + At the same time, `svcs` will pass in all services of A-Server. + ``` + { + "aserver-svc_host": "aserver-svc.", + "aserver-svc_port": [80] # If there are multiple ports in the service, they will be passed in together. + } + ``` + +- Database Information + + | Value | Type | Description | + | -------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------- | + | .Values.postgres.host | String | PostgreSQL database host address | + | .Values.postgres.port | Number | PostgreSQL database port | + | .Values.postgres.username | String | PostgreSQL database username | + | .Values.postgres.password | String | PostgreSQL database password | + | .Values.postgres.databases | Map | PostgreSQL database name. Use the configured database name as the key. For instance, if it's configured as 'app_db', the variable would be `.Values.postgres.databases.app_db`. | + | .Values.mongo.host | String | MongoDB database host address | + | .Values.mongo.port | Number | MongoDB database port | + | .Values.mongo.username | String | MongoDB database username | + | .Values.mongo.password | String | MongoDB database username | + | .Values.mongo.databases | Map | MongoDB database name. Use the configured database name as the key. For instance, if it's configured as 'app_db', the variable would be `.Values.mongo.databases.app_db ` | + | .Values.redis.host | String | Redis database host address | + | .Values.redis.port | Number | Redis database port | + | .Values.redis.password | String | Redis database username | + | .Values.redis.namespaces | Map | Redis namespace. Use the configured namespace as the key. For instance, if it's configured as 'app_ns', the variable would be `.Values.redis.namespaces.app_ns`| \ No newline at end of file diff --git a/docs/developer/develop/package/manifest.md b/docs/developer/develop/package/manifest.md new file mode 100644 index 000000000..0faaad3b8 --- /dev/null +++ b/docs/developer/develop/package/manifest.md @@ -0,0 +1,806 @@ +--- +outline: [2, 3] +--- + +# OlaresManifest Specification + +Every **Olares Application Chart** should include a `OlaresManifest.yaml` file in the root directory. `OlaresManifest.yaml` provides all the essential information about an Olares App. Both the **Olares Market protocol** and the Olares depend on this information to distribute and install applications. + +:::info NOTE +Latest Olares Manifest version: `0.9.0` +- Added a `conflict` field in `options` to declare incompatible applications +- Removed `analytics` field in `options` +- Modified the format of the `tailscale` section +- Added a `allowedOutboundPorts` field to allow non-http protocol external access through the specified port +- Modified the format of the `ports` section + +::: +:::details Changelog +`0.8.3` +- Add a `mandatory` field in the `dependencies` section for dependent applications required for the installation +- Add `tailscaleAcls` section to permit applications to open specified ports via Tailscale + +`0.8.2` +- Add a `runAsUser` option to force the app to run under non root user + +`0.8.1` +- Add a `ports` section to specify exposed ports for UDP or TCP + +`0.7.1` +- Add new `authLevel` value `internal` +- Change `spec`>`language` to `spec`>`locale` and support i18n + ::: + +Here's an example of what a `OlaresManifest.yaml` file might look like: + +::: details OlaresManifest.yaml Example + +```Yaml +olaresManifest.version: '0.8.0' +olaresManifest.type: app +metadata: + name: helloworld + title: Hello World + description: app helloworld + icon: https://file.bttcdn.com/appstore/default/defaulticon.webp + version: 0.0.1 + categories: + - Utilities +entrances: +- name: helloworld + port: 8080 + title: Hello World + host: helloworld + icon: https://file.bttcdn.com/appstore/default/defaulticon.webp + authLevel: private +permission: + appCache: true + appData: true + userData: + - Home/Documents/ + - Home/Pictures/ + - Home/Downloads/BTDownloads/ +spec: + versionName: '0.0.1' + featuredImage: https://link.to/featured_image.webp + promoteImage: + - https://link.to/promote_image1.webp + - https://link.to/promote_image2.webp + fullDescription: | + A full description of your app. + upgradeDescription: | + Describe what is new in this upgraded version. + developer: Developer's Name + website: https://link.to.your.website + sourceCode: https://link.to.sourceCode + submitter: Submitter's Name + language: + - en + doc: https://link.to.documents + supportArch: + - amd64 + limitedCpu: 1000m + limitedMemory: 1000Mi + requiredCpu: 50m + requiredDisk: 50Mi + requiredMemory: 12Mi + +options: + dependencies: + - name: olares + type: system + version: '>=0.1.0' +``` +::: + +## olaresManifest.type + +- Type: `string` +- Accepted Value: `app`, `recommend`, `middleware` + +Olares currently supports 3 types of applications, each requiring different fields. This document uses `app` as an example to explain each field. For information on other types, please refer to the corresponding configuration guide. +- [Recommend Configuration Guide](recommend.md) + +:::info Example +```Yaml +olaresManifest.type: app +``` +::: + +## olaresManifest.version + +- Type: `string` + +As Olares evolves, the configuration specification of `OlaresManifest.yaml` may change. You can identify whether these changes will affect your application by checking the `olaresManifest.version`. The `olaresManifest.version` consists of three integers separated by periods. + +- An increase in the **first digit** indicates the introduction of incompatible configuration items. Applications that haven't updated their `OlaresManifest.yaml` will be unable to distribute or install. +- An increase in the **second digit** signifies changes in the mandatory fields for distribution and installation. However, the Olares remains compatible with the application distribution and installation of previous configuration versions. We recommend developers to promptly update and upgrade the application's `OlaresManifest.yaml` file. +- A change in the **third digit** does not affect the application's distribution and installation. + +Developers can use 1-3 digit version numbers to indicate the application's configuration version. Here are some examples of valid versions: +```Yaml +OlaresManifest.yaml.version: 1 +OlaresManifest.yaml.version: 1.1.0 +OlaresManifest.yaml.version: '2.2' +OlaresManifest.yaml.version: "3.0.122" +``` + +## Metadata + +Basic information about the app shown in the system and Olares Market. + +:::info Example +```Yaml +metadata: + name: nextcloud + title: Nextcloud + description: The productivity platform that keeps you in control + icon: https://file.bttcdn.com/appstore/nextcloud/icon.png + version: 0.0.2 + categories: + - Utilities + - Productivity +``` +::: + +### name + +- Type: `string` +- Accepted Value: `[a-z][a-z0-9]?` + +App’s namespace in Olares, lowercase alphanumeric characters only. It can be up to 30 characters, and needs to be consistent with `FolderName` and `name` field in `Chart.yaml`. + +### title + +- Type: `string` + +The title of your app title shown in the Olares Market. Must be within `30` characters. + +### description + +- Type: `string` + +A short description appears below app title in the Olares Market. + +### icon + +- Type: `url` + +Your app icon that appears in the Olares Market. + +The app's icon must be a `PNG` or `WEBP` format file, up to `512 KB`, with a size of `256x256 px`. + +### version + +- Type: `string` + +The **Chart Version** of the application. It should be incremented each time the content in the **Chart** changes. It should follow the [Semantic Versioning 2.0.0](https://semver.org/) and needs to be consistent with the `version` field in `Chart.yaml`. + +### categories + +- Type: `list` +- Accepted Value: `Blockchain`, `Utilities`, `Social Network`, `Entertainment`, `Productivity` + +Used to display your app on different category page in Olares Market. + +## Entrances + +The number of entrances through which to access the app. You must specify at least 1 access method, with a maximum of 10 allowed. + +:::info Example +```Yaml +entrances: +- name: a + host: firefox + port: 3000 + title: Firefox + authLevel: public + invisible: false +- name: b + host: firefox + port: 3001 + title: admin +``` +::: + +### name + +- Type: `string` +- Accepted Value: `[a-z]([-a-z0-9]*[a-z0-9])?` + + Name of the Entrance. It can be up to `63` characters, and needs to be unique in an app. + +### port + +- Type: `int` +- Accepted Value: `0-65535` + +### host + +- Type: `string` +- Accepted Value: `[a-z]([-a-z0-9]*[a-z0-9])?` + + Ingress name of current entrance, lowercase alphanumeric characters and `-` only. It can be up to `63` characters. + +### title + +- Type: `string` + +Title that appears in the Olares desktop after installed. It can be up to `30` characters. + +### icon + +- Type: `url` +- Optional + +Icon that appears in the Olares desktop after installed. The app's icon must be a `PNG` or `WEBP` format file, up to `512 KB`, with a size of `256x256 px`. + +### authLevel + +- Type: `string` +- Accepted Value: `public`, `private`, `internal` +- Default: `private` +- Optional + +Specify the authentication level of the entrance. +- **Public**: Accessible by anyone on the Internet without restrictions. +- **Private**: Requires authorization for access from both internal and external networks. +- **Internal**: Requires authorization for access from external networks. No authentication is required when accessing from within the internal network (via LAN/VPN). + +### invisible + +- Type: `boolean` +- Default: `false` +- Optional + +When `invisible` is `true`, the entrance will not be displayed on the Olares desktop. + +### openMethod + +- Type: `string` +- Accepted Value: `default`, `iframe`, `window` +- Default: `default` +- Optional + +Explicitly defines how to open this entrance in Desktop. + +The `iframe` creates a new window within the desktop window through an iframe. The `window` opens a new tab in the browser. The `default` follows the system setting, which is `iframe` by default. + +### windowPushState +- Type: `boolean` +- Default: `false` +- Optional + +When embedding the application in an iframe on the desktop, the application's URL may change dynamically. Due to browser's same-origin policy, the desktop (parent window) cannot directly detect these changes in the iframe URL. Consequently, if you reopen the application tab, it will display the initial URL instead of the updated one. + +To ensure a seamless user experience, you can enable this option by setting it to true. This action prompts the gateway to automatically inject the following code into the iframe. This code sends an event to the parent window (desktop) whenever the iframe's URL changes. As a result, the desktop can track URL changes and open the correct page. + +::: details Code +```Javascript + +``` +::: + +## Ports + +Specify exposed ports + +:::info Example +```Yaml +ports: +- name: rdp-tcp # Name of the entrance that provides service + host: windows-svc # Ingress name of the entrance that provides service + port: 3389 # Port of the entrance that provides service + exposePort: 46879 # The port to be exposed can only be assigned to one application at a time within the cluster. + addToTailscaleAcl: true # Automatically added to Tailscle's ACL +``` +::: + +Olares will expose the ports you specify for an application, which are accessible via the application domain name in the local network, for example: `84864c1f.your_olares_id.olares.com:46879`. For each port you expose, Olares configures both TCP and UDP with the same port number. + +When the `addToTailscaleAcl` field is set to `true`, the port will be automatically added to the Tailscale's ACL, and there is no need to configure in the tailscale section. + +:::info NOTE +The exposed ports can only be accessed on the local network or through a VPN. +::: + +## Permission + +:::info Example +```Yaml +permission: + appCache: true + appData: true + userData: + - /Home/ + sysData: + - dataType: legacy_prowlarr + appName: prowlarr + port: 9696 + group: api.prowlarr + version: v2 + ops: + - All +``` +::: + +### appCache + +- Type: `boolean` +- Optional + +Whether the app requires read and write permission to the `Cache` folder. If `.Values.userspace.appCache` is used in the deployment YAML, then `appCache` must be set to `true`. + +### appData + +- Type: `boolean` +- Optional + +Whether the app requires read and write permission to the `Data` folder. If `.Values.userspace.appData` is used in the deployment YAML, then `appData` must be set to `true`. + +### userData + +- Type: `list` +- Optional + +Whether the app requires read and write permission to user's `Home` folder. List all directories that the application needs to access under the user's `Home`. All `userData` directory configured in the deployment YAML, must be included here. + +### sysData + +- Type: `list` +- Optional + +Declare the list of APIs that this app needs to access. + +:::info Example +```Yaml + sysData: + - group: service.bfl + dataType: app + version: v1 + ops: + - InstallDevApp + - dataType: legacy_prowlarr + appName: prowlarr + port: 9696 + group: api.prowlarr + version: v2 + ops: + - All +``` +::: + +All system API [providers](../advanced/provider.md) are list below: +| Group | version | dataType | ops | +| ----------- | ----------- | ----------- | ----------- | +| service.appstore | v1 | app | InstallDevApp, UninstallDevApp +| message-dispatcher.system-server | v1 | event | Create, List +| service.desktop | v1 | ai_message | AIMessage +| service.did | v1 | did | ResolveByDID, ResolveByName, Verify +| api.intent | v1 | legacy_api | POST +| service.intent | v1 | intent | RegisterIntentFilter, UnregisterIntentFilter, SendIntent, QueryIntent, ListDefaultChoice, CreateDefaultChoice, RemoveDefaultChoice, ReplaceDefaultChoice +| service.message | v1 | message | GetContactLogs, GetMessages, Message +| service.notification | v1 | message | Create +| service.notification | v1 | token | Create +| service.search | v1 | search | Input, Delete, InputRSS, DeleteRSS, QueryRSS, QuestionAI +| secret.infisical | v1 | secret | CreateSecret, RetrieveSecret +| secret.vault | v1 | key | List, Info, Sign + +## Tailscale +- Type: `map` +- Optional + +Allow applications to add Access Control Lists (ACL) in Tailscale to open specified ports. + +:::info Example +```Yaml +tailscale: + acls: + - proto: tcp + dst: + - "*:46879" + - proto: "" # Optional. If not specified, all supported protocols will be allowed. + dst: + - "*:4557" +``` +::: + +## Spec +Additional information about the application, primarily used for display in the Olares Market. + +:::info Example +```Yaml +spec: + namespace: os-system + # optional. Install the app to a specified namespace, e.g. os-system, user-space, user-system + + versionName: '10.8.11' + # The version of the application that this chart contains. It is recommended to enclose the version number in quotes. This value corresponds to the appVersion field in the `Chart.yaml` file. Note that it is not related to the `version` field. + + featuredImage: https://file.bttcdn.com/appstore/jellyfin/promote_image_1.jpg + # The featured image is displayed when the app is featured in the Market. + + promoteImage: + - https://file.bttcdn.com/appstore/jellyfin/promote_image_1.jpg + - https://file.bttcdn.com/appstore/jellyfin/promote_image_2.jpg + - https://file.bttcdn.com/appstore/jellyfin/promote_image_3.jpg + fullDescription: | + Jellyfin is the volunteer-built media solution that puts you in control of your media. Stream to any device from your own server, with no strings attached. Your media, your server, your way. + upgradeDescription: | + upgrade descriptions + developer: Jellyfin + website: https://jellyfin.org/ + doc: https://jellyfin.org/docs/ + sourceCode: https://github.com/jellyfin/jellyfin + submitter: Olares + locale: + - en-US + - zh-CN + # List languages and regions supported by this app + + requiredMemory: 256Mi + requiredDisk: 128Mi + requiredCpu: 0.5 + # Specifies the minimum resources required to install and run the application. Once the app is installed, the system will reserve these resources to ensure optimal performance. + + limitedDisk: 256Mi + limitedCpu: 1 + limitedMemory: 512Mi + # Specifies the maximum resource limits for the application. If the app exceeds these limits, it will be temporarily suspended to prevent system overload and ensure stability. + + legal: + - text: Community Standards + url: https://jellyfin.org/docs/general/community-standards/ + - text: Security policy + url: https://github.com/jellyfin/jellyfin/security/policy + license: + - text: GPL-2.0 + url: https://github.com/jellyfin/jellyfin/blob/master/LICENSE + supportClient: + - android: https://play.google.com/store/apps/details?id=org.jellyfin.mobile + - ios: https://apps.apple.com/us/app/jellyfin-mobile/id1480192618 +``` +::: + +### i18n + +To add multi-language support for your app in Olares Market: + +1. Create an `i18n` folder in the Olares Application Chart root directory. +2. In the `i18n` folder, create separate subdirectories for each supported locale. +3. In each locale subdirectory, place a localized version of the `OlaresManifest.yaml` file. + +Olares Market will automatically display the content of the corresponding "OlaresManifest.yaml" file based on users' locale settings. +:::info Example +``` +. +├── Chart.yaml +├── README.md +├── OlaresManifest.yaml +├── i18n +│ ├── en-US +│ │ └── OlaresManifest.yaml +│ └── zh-CN +│ └── OlaresManifest.yaml +├── owners +├── templates +│ └── deployment.yaml +└── values.yaml +``` +::: +Currently, you can add i18n content for the following fields: +```Yaml +metadata: + description: + title: +spec: + fullDescription: + upgradeDescription: +``` + +### supportArch +- Type: `list` +- Accepted Value: `amd64`, `arm64` +- Optional + +Specifies the CPU architecture supported by the application. Currently only `amd64` and `arm64` are available. + +:::info Example +```yaml +spec: + supportArch: + - amd64 + - arm64 +``` +::: + +:::info NOTE +Olares does not support mixed-architecture clusters for now. +::: + +### onlyAdmin +- Type: `boolean` +- Default: `false` +- Optional + +When set to `true`, only the admin can install this app. + +### runAsUser +- Type: `boolean` +- Optional + +When set to `true`, Olares forces the application to run under user ID `1000` (as a non-root user). + +## Middleware +- Type: `map` +- Optional + +The Olares provides highly available middleware services. Developers do not need to install middleware repeatedly. Just simply add required middleware here, You can then directly use the corresponding middleware information in the application's deployment YAML file. + +Use the `scripts` field to specify scripts that should be executed after the database is created. Additionally, use the `extension` field to add the corresponding extension in the database. + +:::info Example +```Yaml +middleware: + postgres: + username: immich + databases: + - name: immich + extensions: + - vectors + - earthdistance + scripts: + - BEGIN; + - ALTER DATABASE $databasename SET search_path TO "$user", public, vectors; + - ALTER SCHEMA vectors OWNER TO $dbusername; + - COMMIT; + # The OS provides two variables, $databasename and $dbusername, which will be replaced by Olares Application Runtime when the command is executed. + redis: + password: password + namespace: db0 + mongodb: + username: chromium + databases: + - name: chromium + script: + - 'db.getSiblingDB("$databasename").myCollection.insertOne({ x: 111 });' + # Please make sure each line is a complete query. +``` +::: + +Use the middleware information in deployment YAML + +```yaml +- name: DB_POSTGRESDB_DATABASE # The database name you configured in OlaresManifest, specified in middleware.postgres.databases[i].name + value: {{ .Values.postgres.databases. }} +- name: DB_POSTGRESDB_HOST + value: {{ .Values.postgres.host }} +- name: DB_POSTGRESDB_PORT + value: "{{ .Values.postgres.port }}" +- name: DB_POSTGRESDB_USER + value: {{ .Values.postgres.username }} +- name: DB_POSTGRESDB_PASSWORD + value: {{ .Values.postgres.password }} + + +# For mongodb, the corresponding value is as follows +host --> {{ .Values.mongodb.host }} +port --> "{{ .Values.mongodb.port }}" # The port and password in the yaml file need to be enclosed in double quotes. +username --> {{ .Values.mongodb.username }} +password --> "{{ .Values.mongodb.password }}" # The port and password in the yaml file need to be enclosed in double quotes. +databases --> "{{ .Values.mongodb.databases }}" # The value type of database is a map. You can get the database using {{ .Values.mongodb.databases. }}. The is the name you configured in OlaresManifest, specified in middleware.mongodb.databases[i].name + + +# For Redis, the corresponding value is as follows +host --> {{ .Values.redis.host }} +port --> "{{ .Values.redis.port }}" +password --> "{{ .Values.redis.password }}" + +``` + +## Options + +Configure system-related options here. + +### policies +- Type: `map` +- Optional + +Define detailed access control for subdomains of the app. + +:::info Example +```yaml +options: + policies: + - uriRegex: /$ + level: two_factor + oneTime: false + validDuration: 3600s + entranceName: gitlab +``` +::: + +### clusterScoped +- Type: `map` +- Optional + +Whether this app is installed for all users in an Olares cluster. + +:::info Example For Server +```yaml +metadata: + name: gitlab +options: + appScope: + clusterScoped: true + appRef: + - gitlabclienta #app name of clients + - gitlabclientb +``` +::: + +:::info Example For Client +```yaml +metadata: + name: gitlabclienta +options: + dependencies: + - name: olares + version: ">=0.3.6-0" + type: system + - name: gitlab #app name of server + version: ">=0.0.1" + type: application + mandatory: true +``` +::: + + +### dependencies +- Type: `list` + +Specify the dependencies and requirements for your application. It includes other applications that your app depends on, as well as any specific operating system (OS) version requirements. + +If this application requires other dependent applications for proper installation, you should set the `mandatory` field to `true`. + +:::info Example +```yaml +options: + dependencies: + - name: olares + version: ">=1.0.0-0" + type: system + - name: mongodb + version: ">=6.0.0-0" + type: middleware + mandatory: true # Set this field to true if the dependency needs to be installed first. +``` +::: + +### websocket +- Type: `map` +- Optional + +Enable websocket for the app. Refer to [websocket](../advanced/websocket.md) for more information. + +:::info Example +```yaml +options: + websocket: + url: /ws/message + port: 8888 +``` +::: + +### resetCookie +- Type: `map` +- Optional + +If the app requires cookies, please enable this feature. Refer to [cookie](../advanced/cookie.md) for more information. + +:::info Example +```yaml +options: + resetCookie: + enabled: true +``` +::: + +### upload +- Type: `map` +- Optional + +The Olares Application Runtime includes a built-in file upload component designed to simplify the file upload process in your application. Refer to [upload](../advanced/file-upload.md) for more information. + +:::info Example +```yaml +upload: + # The types of files that are allowed to be uploaded, * stands for any type, The type of the uploaded file must be in the list. + fileType: + - pdf + # The path of 'dest' must be a mountPath + dest: /appdata + # The maximum size of file, in bytes + limitedSize: 3729747942 +``` +::: + +### mobileSupported +- Type: `boolean` +- Default: `false` +- Optional + +Determine whether the application is compatible with mobile web browsers and can be displayed on the mobile version of Olares Desktop. Enable this option if the app is optimized for mobile web browsers. This will make the app visible and accessible on the mobile version of Olares Desktop. + +:::info Example +```yaml +mobileSupported: true +``` +::: + +### oidc +- Type: `map` +- Optional + +The Olares includes a built-in OpenID Connect authentication component to simplify identity verification of users. Enable this option to use OpenID in your app. +```yaml +# OpenID related variables in yaml +{{ .Values.oidc.client.id }} +{{ .Values.oidc.client.secret }} +{{ .Values.oidc.issuer }} +``` + +:::info Example +```yaml +oidc: + enabled: true + redirectUri: /path/to/uri + entranceName: navidrome +``` +::: + +### apiTimeout +- Type: `int` +- Optional + +Specifies the timeout limit for API providers in seconds. The default value is `15`. Use `0` to allow an unlimited API connection. + +:::info Example +```yaml +apiTimeout: 0 +``` +::: + + + +### allowedOutboundPorts +- Type: `map` +- Optional + +​​The specified ports will be opened to allow external access via non-HTTP protocols, such as SMTP. + +:::info Example +```yaml +allowedOutboundPorts: + - 465 + - 587 +``` +::: \ No newline at end of file diff --git a/docs/developer/develop/package/recommend.md b/docs/developer/develop/package/recommend.md new file mode 100644 index 000000000..f93a34269 --- /dev/null +++ b/docs/developer/develop/package/recommend.md @@ -0,0 +1,320 @@ +# Configuration Guideline for Recommend + +When creating an application chart for `recommend`, you'll primarily need to configure the four files located in the `templates/` folder: `embedding.yaml`, `prerank.yaml`, `rank.yaml`, `train.yaml`. + + +## embedding.yaml + +::: details embedding.yaml Example + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: user-embedding-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '0 */1 * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Replace + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: userEmbeddingFlow + volumes: + - name: huggingface + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/model/huggingface + templates: + - name: userEmbeddingFlow + steps: + - - name: user-embedding + template: user-embedding-template + - name: user-embedding-template + container: + image: 'beclab/r4userembedding' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /root/.cache/huggingface + name: huggingface +``` + +::: + +### Field Description + | +| Field | Description | +| -------------------------- | ------------------------------------------------------------------------------------------ | +| apiVersion | The API version in use. | +| kind | Defines a CronWorkflow object. | +| metadata.name | The name of the CronWorkflow. | +| metadata.namespace | The namespace that the CronWorkflow belongs to. | +| spec.schedule | Cron expression, defines the scheduling time of the CronWorkflow. | +| spec.startingDeadlineSeconds | The start deadline of the CronWorkflow, represents the maximum delay time from the scheduled time. | +| spec.concurrencyPolicy | Concurrency policy, specifies how to handle the currently running job when the next schedule time of the CronWorkflow arrives. | +| spec.successfulJobsHistoryLimit | The limit of the successful job history record. | +| spec.failedJobsHistoryLimit | The limit of the failed job history record. | +| spec.suspend | Indicates whether to suspend the operation of the CronWorkflow. | +| spec.ttlStrategy.secondsAfterSuccess | The time to live after the successful job is completed, in seconds. | +| spec.ttlStrategy.secondsAfterCompletion | The time to live after the job is completed, in seconds. | +| spec.ttlStrategy.secondsAfterFailure | The time to live after the failed job is completed, in seconds. | +| spec.workflowSpec.entrypoint | The entry point of the Workflow. | +| spec.workflowSpec.volumes[0].name | The definition of the volume, the name is huggingface. | +| spec.workflowSpec.volumes[0].hostPath.type | The host machine path type, specified as a directory or create a directory. | +| spec.workflowSpec.volumes[0].hostPath.path | The path of the host machine. | +| spec.workflowSpec.templates[0].name | The name of the Workflow template. | +| spec.workflowSpec.templates[0].steps[0][0].name | The definition of the step, its name. | +| spec.workflowSpec.templates[0].steps[0][0].template | The name of the referenced template. | +| spec.workflowSpec.templates[1].name | The name of the template. | +| spec.workflowSpec.templates[1].container.image | The image name of the container. | +| spec.workflowSpec.templates[1].container.imagePullPolicy | The image pull policy. | +| spec.workflowSpec.templates[1].container.env[0].name | The definition of the environment variable, its name. | +| spec.workflowSpec.templates[1].container.env[0].value | The value of the environment variable. | +| spec.workflowSpec.templates[1].container.env[1].name | The definition of the environment variable, its name. | +| spec.workflowSpec.templates[1].container.env[1].value | The value of the environment variable. | +| spec.workflowSpec.templates[1].container.volumeMounts[0].mountPath | The definition of the mount path. | +| spec.workflowSpec.templates[1].container.volumeMounts[0].name | The name of the mounted volume. | + +## prerank.yaml + +::: details prerank.yaml Example + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: prerank-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '*/5 * * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Replace + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: algorithm + volumes: + - name: nfs + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/data + - name: juicefs + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/data + templates: + - name: algorithm + steps: + - - name: recall + template: recall-template + - - name: prerank + template: prerank-template + - name: recall-template + container: + image: 'beclab/r4recall:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: NFS_ROOT_DIRECTORY + value: /nfs + - name: JUICEFS_ROOT_DIRECTORY + value: /juicefs + - name: ALGORITHM_FILE_CONFIG_PATH + value: /usr/config/ + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + - name: SUPPORT_LANGUAGE + value: en + - name: SUPPORT_TIMELINESS + value: '0' + - name: SYNC_PROVIDER + value: bytetrade + - name: SYNC_FEED_NAME + value: sport + - name: SYNC_MODEL_NAME + value: bert_v2 + volumeMounts: + - mountPath: /nfs + name: nfs + - mountPath: /juicefs + name: juicefs + - name: prerank-template + container: + image: 'beclab/r4prerank:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: NFS_ROOT_DIRECTORY + value: /nfs + - name: JUICEFS_ROOT_DIRECTORY + value: /juicefs + - name: ALGORITHM_FILE_CONFIG_PATH + value: /usr/config/ + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + - name: SUPPORT_LANGUAGE + value: en + - name: SUPPORT_TIMELINESS + value: '0' + volumeMounts: + - mountPath: /nfs + name: nfs + - mountPath: /juicefs + name: juicefs + +``` + +::: + + +## rank.yaml + +::: details rank.yaml Example + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: rank-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '*/5 * * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Forbid + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: rankFlow + volumes: + - name: model + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/model + templates: + - name: rankFlow + steps: + - - name: extractor + template: extractor-template + - - name: rank + template: rank-template + - name: extractor-template + container: + image: 'beclab/r4extractor:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + - name: rank-template + container: + image: 'beclab/r4rank' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + + +``` + +::: + + +## train.yaml + +::: details train.yaml Example + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: rank-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '*/5 * * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Forbid + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: rankFlow + volumes: + - name: model + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/model + templates: + - name: rankFlow + steps: + - - name: extractor + template: extractor-template + - - name: rank + template: rank-template + - name: extractor-template + container: + image: 'beclab/r4extractor:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + - name: rank-template + container: + image: 'beclab/r4rank' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + +``` +::: \ No newline at end of file diff --git a/docs/developer/develop/submit/index.md b/docs/developer/develop/submit/index.md new file mode 100644 index 000000000..99ee35bd2 --- /dev/null +++ b/docs/developer/develop/submit/index.md @@ -0,0 +1,123 @@ +--- +outline: [2, 3] +--- + +# Submit Application + +## Submitting Your Application + +**Brief Overview** + +1. Test your application on Olares, create the Olares Application Chart according to [guideline](../package/chart.md). +2. Fork the official [application repository of Olares Market](https://github.com/beclab/apps). Add your application's chart. Create a **PR** to `beclab/apps:main`. +3. Wait for **GitBot** to check your PR. If needed, modify PR until it passes. +4. Once the PR is merged, your application is ready to launch. + + +### 1. Develop and test your application + +Before submitting an application, please ensure that it has been thoroughly tested on your Olares. +- Use DevBox's dev-container to test and debug your application in a real online environment. [Learn more about DevBox](../tutorial/studio). +- Use the [custom installation](/manual/olares/market.md#install-custom-applications) in the Market app for user testing. + +### 2. Submit an application +The submission of the application needs to be completed through a **Pull Request**. Here's how: +- Fork the official [application repository of Olares Market](https://github.com/beclab/apps) and add your application's chart in your forked repository. +- Create a `Draft PR` pointing to `beclab/apps:main`. +- Please edit your PR title and text according to the template. + - **PR Title** must in this format: [PR Type][FolderName][version]Title Content + - `PR Type` includes: + - NEW: Submit a new application + - UPDATE: Update an already successfully merged application + - REMOVE: Remove an already successfully merged application + - SUSPEND: Suspend an already successfully merged application from distribution through the application store + - `FolderName` is your Olares Application Chart name. It must adhere to the naming requirements in [chart specification](../package/chart.md). + - `version` refers to your application chart's `Chart Version`, which needs to be consistent with the `version` field in `Chart.yaml` and metadata section of `OlaresManifest.yaml` +- To prevent your PR from being incorrectly parsed or closed, please adhere to the following rules: + - Your PR title must contain only one `PR Type`, `FolderName`, and `version`. + - Your `PR Type` must be one of the predefined types. + - A PR should only add or modify content under the `FolderName` declared in the PR title. + - Only one Open PR or Draft PR can exist at a time with the same `FolderName`. + - You must be one of the owners of the folder you wish to modify. Owners are listed in the `owners` file within the chart. If you're submitting a new application, your GitHub username should be included in the `owners` file. + +- During the Draft PR phase, you can continuously adjust your PR content and add new commits. Once everything is ready, click on the **'Ready for review'** button to submit the PR and call on **GitBot** to check. + +:::info NOTE +The title and content of the PR are crucial for **GitBot**. Please adhere to the template specifications when filling them out. **GitBot** may automatically close any invalid PRs. +::: + +### 3. Track your PR status +- When your PR is labeled with `PR type`, it indicates that your PR title is valid. Please **do not modify the `PR Type` afterwards.** If it doesn't reflect your intentions, simply close it and create a new one. + +- You can track the progress of your PR through the status tags: + - `waiting to submit`: your PR has an issue and requires further modification before merging. + - `closed`: your PR is invalid or contains uncorrectable errors. + - `waiting to merge`: Everything is progressing smoothly. Your PR has passed the check and is now awaiting auto-merge by the **GitBot**. + - `merged`: your PR has been automatically merged into the `beclab/apps:main`. + +- If **GitBot** automatically closes your PR, please **do not reopen** it. This implies that the PR has irreparable issues, and **GitBot** had to terminate the check process. You can submit a new PR after making necessary modifications. + +- During the `waiting to submit` state, you can continue to submit commits to modify your application chart. **GitBot** will recheck the application chart files and update the PR status upon receiving a new commit. + +- Once your PR passes all checks, it will be automatically merged into the `beclab/apps:main`. The application will be listed on **Olares Market** after a while. + +- If you encounter any issues during the submission process, feel free to reach out to the Olares team or seek assistance from the community. + +## Managing Your Application + +You can continue managing and maintaining your application by creating a Pull Request to `beclab/apps:main`. You can upgrade your application, modify its availability, or completely remove it from the **Olares Market**. + +The process of managing applications is similar to submission.You create a specific type of Pull Request, and GitBot takes care of the rest. Olares uses **special control files** in the root directory of application chart to manage the application's status. These **special control files** are empty files with specific suffix, such as `.suspend` and `.remove` + +:::info NOTE +No ".suspend" or ".remove" files should be included in the initial submission. +::: + +### Update +When you need to update a published application, you need to create an `UPDATE` PR. + +**Please note:** +- Whenever you make changes to your application chart, such as upgrade the program, update metadata, or change owner list, be sure to upgrade your chart version. +- The chart version in the updated application chart must be ***greater than*** the current version in the repository. +- No `.suspend` or `.remove` files included in the root directory of updated application chart. +- The **Olares Market** does not offer version rollback. If there are any issues with your application, you need to submit a new version to fix it. +- To avoid potential conflicts, we recommend syncing your fork and rebase the commits of PR to the latest main branch. + +### Suspend +If for any reason you want to temporarily disable your application's download and installation from the **Olares Market**, submit a `SUSPEND` PR. + +**Please note:** +- The chart version in the submitted application chart must ***match*** the current version in the repository. +- The root directory you submit should contain the `.suspend` file and should not contain the `.remove` file. +- Once the suspend PR passes check and merges, the application store will stop listing your application. +- Users who have already downloaded and installed the application can continue to use it after suspension. + +### Remove +If for any reason you want to remove your application from the **Olares Market**, submit a `REMOVE` PR. + +**Please note:** +- Completely empty the files in the current application directory and add a `.remove` file to the root directory. +- Once the remove PR passes check and merges, the application store will remove your application. +- You will not be able to reuse the same directory or application chart name in the future. +- Users who have already downloaded and installed the application can continue to use it after removal. + +## Promoting Your Application + +Utilizing well-organized application descriptions, screenshots, and promotional images to highlight the features and functions of your application can help attract new users in the Market. Screenshots and previews can intuitively demonstrate the user experience, helping your application stand out. + +To add promotional images on the application detail page, include links to these assets in the `promoteImage` fields within the `spec` section of the `OlaresManifest.yaml` file. + +:::info **Assets Specifications for the Olares Market** + +- The application's **icon** must be in PNG or WEBP format, up to 512 KB, with a size of 256x256 px. + +- It is highly recommended to upload at least 2 **screenshots** for promotion. **Screenshots** must be in JPEG, PNG, or WEBP format, up to 8MB each, with a size of 1440x900 px. You can upload up to 8 **screenshots**. + +- If you wish to have your application featured in the store, a **featured image** is required. Add a link to this image in the `featuredImage` field within the `spec` section of the `OlaresManifest.yaml` file. The image must be in JPEG, PNG, or WEBP format, up to 8MB, with a size of 1440x900 px +::: + +## Inviting Others to Collaborate + +There are two ways to invite others to develop Olares applications together: +1. Add others developer's GitHub usernames to the `owners` file. Each developer listed in `owners` can then fork the repository and submit their changes independently. +2. Add others as collaborators to your forked repository. In this case, you create the Pull Request as a representative, and all others can jointly commit to the branch that is planned to merge. diff --git a/docs/developer/develop/tutorial/index.md b/docs/developer/develop/tutorial/index.md new file mode 100644 index 000000000..cd549cb40 --- /dev/null +++ b/docs/developer/develop/tutorial/index.md @@ -0,0 +1,15 @@ +# Tutorial + +Welcome to the Olares developer guides. These detailed tutorials offer a step-by-step guide on building an Olares Application from scratch. + +To get started, you can learn some basic concepts of Olares, such as: +- [Olares architectural components](../../../manual/concepts/architecture.md) +- [Olares Application Chart](../../develop/package/chart.md) +- [Olares Extension on Helm](../package/extension.md) + +These fundamentals will help you grasp our development process more effectively. + +You can also [learn about DevBox](studio.md), a built-in app that Olares provides for developers to build Olares applications. + +If you're brand new to Olares development and want to jump straight into coding, start with the [**Create your first Olares app**](./note/index.md). This tutorial will step you through the process of building a small note application. + diff --git a/docs/developer/develop/tutorial/note/backend.md b/docs/developer/develop/tutorial/note/backend.md new file mode 100644 index 000000000..6e85b969c --- /dev/null +++ b/docs/developer/develop/tutorial/note/backend.md @@ -0,0 +1,71 @@ +# Develop Backend Program + +## Clone Code + + Open the IDE of backend Dev Container, open Terminal, clone your code to the `/Code` directory + + ```sh + gh auth login + + cd /Code + git clone https://github.com/beclab/terminus-app-demo.git + ``` + + You can then open the backend code in the IDE for development. + + ![server IDE](/images/developer/develop/tutorial/backend/dev.jpg) + +## Connect Database + + In the Dev Container, you can access database details through environment variables. You can do this by adding the database parameters into the container using environment variables when you deploy it. + + Take `gorm` as an example: + ```go + import ( + "fmt" + "os" + "strconv" + + "gorm.io/driver/postgres" + "gorm.io/gorm" + ) + + + func init() { + var err error + + db_host = os.Getenv("DB_HOST") + db_port, err = strconv.Atoi(os.Getenv("DB_PORT")) + if err != nil { + panic(err) + } + db_username = os.Getenv("DB_USER") + db_password = os.Getenv("DB_PWD") + db_name = os.Getenv("DB_NAME") + } + + + func main(){ + dsn := fmt.Sprintf("host=%s user=%s password=%s dbname=%s port=%d sslmode=disable TimeZone=Asia/Shanghai", + db_host, db_username, db_password, db_name, db_port) + db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{}) + if err != nil { + panic(err) + } + + } + ``` + +## Debug + + After completing the development, you can run and debug your code in the IDE. + + ![run and debug](/images/developer/develop/tutorial/backend/debug.jpg) + + You can also run your code in the Terminal, for example: + + ```sh + go run main.go + ``` + + Now, you can debug your interface with your front-end program. \ No newline at end of file diff --git a/docs/developer/develop/tutorial/note/create.md b/docs/developer/develop/tutorial/note/create.md new file mode 100644 index 000000000..9bc5a42cc --- /dev/null +++ b/docs/developer/develop/tutorial/note/create.md @@ -0,0 +1,201 @@ +--- +outline: [2, 3] +--- + +# How to Start Developing an Application + +## Install and Launch DevBox + +1. Install [DevBox](https://market.olares.com/app/devbox) from the Olares Market. +2. Find the DevBox icon in the launcher panel on the Olares Desktop. +3. Click on the icon to launch the application. + +![main screen](/images/developer/develop/tutorial/create/home.jpg) + +## Create Your App + +Click the **Create a new application** to create a blank Olares application from a template. + +- In the **App Name** field, enter your application name. +- Set the **APP type** to **app**. +- Change the **Main Entrance Port** for your APP entrance. +- In the **Image** field, input the image name and tag from your image repository where your app image will be stored. + +![create app](/images/developer/develop/tutorial/create/create.jpg) + +## Setup App Config + +After creating the application, you can see the Olares Application Chart files generated by DevBox under the **Files** Tab. You can add, delete, or rename various configuration files as needed. + +![upload icon](/images/developer/develop/tutorial/create/add-file.jpg) + +### Chart.yaml + +The `Chart.yaml` file is a required file in the Helm Chart specification. It contains the application's `Name` and `Chart Version`. You can [learn more here](https://helm.sh/docs/topics/charts/). For now, we're not going to change the default `Chart.yaml` yet. + +### OlaresManifest.yaml + +In the `OlaresManifest.yaml `file, you can change many configurations. This includes but is not limited to: + +- Changing the app's title, icon, and other details +- Adding system `middleware` +- Getting `permissions` for system directory access +- Changing the `required and limited resource` of the app + +#### Adding a [cluster database middleware](../../package/manifest.md#middleware) + +![config app](/images/developer/develop/tutorial/create/olares-manifest.jpg) + +In this example, we will configure a PostgreSQL database. Add the following content to the configuration file: + +```Yaml +middleware: + postgres: + username: postgres + databases: + - name: db + distributed: false +``` + +You can specify your database `username` and `password` in the configuration. Alternatively, you can leave these fields empty and use the system-generated random password instead. You need to set the database `name` required by your APP. In addition, you can also choose to apply for a `distributed database`. If so, the system will create a [citus](https://github.com/citusdata/citus) database for you. + +After completing the configuration, you can reference the corresponding database configuration in your `deployment.yaml`. For example, reference in the environment variables of the container. + +```yaml +- env: + - name: DB_PORT + value: "{{ .Values.postgres.port }}" + - name: DB_NAME + value: "{{ .Values.postgres.databases.demo }}" + - name: DB_USER + value: "{{ .Values.postgres.username }}" + - name: DB_HOST + value: "{{ .Values.postgres.host }}" + - name: DB_PWD + value: "{{ .Values.postgres.password }}" +``` + +- `.Values.postgres.username`: the `username` of PostgreSQL in configuration. +- `.Values.postgres.databases.demo`: the `database name` in configuration. +- `.Values.postgres.password`: the `password` in configuration. +- `.Values.postgres.host`: the database service address specified by the system for the APP. +- `.Values.postgres.port`: the database service port specified by the system for the APP. + +::: warning +These parameters should not be hardcoded, they must reference the variables passed in by the system, and the system will randomize the database information in the configuration. +::: + +#### Adding [Access Permissions to the File System](../../package/manifest.md#permission) + +To read and save files in the Olares system, we need to configure Access Permissions for certain file directories. These directories can be specified in the `Permissions` section of the `OlaresManifest.yaml` file: + +- `appData`: This applies for independent cloud storage space for the app. +- `appCache`: This applies for local disk data cache space, usually on an SSD disk, for the app. +- `userData`: This applies for access permission to the user's data directory. List the directories you need to access here. + +After completing the above configuration, you can reference these configurations in your deployment + +```yaml +volumes: + - hostPath: + path: "{{ .Values.userspace.appCache }}/demo" + type: DirectoryOrCreate + name: appcache + - hostPath: + path: "{{ .Values.userspace.appData }}/demo" + type: DirectoryOrCreate + name: appdata +``` + +- `.Values.userspace.appCache` is the `appCache` directory +- `.Values.userspace.appData` is the `appData` directory +- `.Values.userspace.userData` is the `userData` directory + +### deployment.yaml + +The `deployment.yaml` in the `templates` folder details the deployment configuration of your application. + +If your app includes several containers, such as front-end and back-end, you can add multiple containers in the `deployment.yaml` file in the `templates`. DevBox will recognize these different containers and bind each of them separately to different development containers. For example: + +```yaml +containers: + # front-end container + - env: + - name: PGID + value: "1000" + - name: PUID + value: "1000" + - name: TZ + value: Etc/UTC + image: bytetrade/demo-app:0.0.1 + name: demo + ports: + - containerPort: 8080 + resources: + limits: + cpu: "1" + memory: 2000Mi + requests: + cpu: 50m + memory: 1000Mi + volumeMounts: + - mountPath: /appcache + name: appcache + + # Server container + - env: + - name: DB_PORT + value: "{{ .Values.postgres.port }}" + - name: DB_NAME + value: "{{ .Values.postgres.databases.demo }}" + - name: DB_USER + value: "{{ .Values.postgres.username }}" + - name: DB_HOST + value: "{{ .Values.postgres.host }}" + - name: DB_PWD + value: "{{ .Values.postgres.password }}" + - name: PGID + value: "1000" + - name: PUID + value: "1000" + - name: TZ + value: Etc/UTC + image: bytetrade/demo-server:0.0.1 + name: server + ports: + - containerPort: 9000 + resources: + limits: + cpu: "1" + memory: 1000Mi + requests: + cpu: 50m + memory: 500Mi + volumeMounts: + - mountPath: /appcache + name: appcache + - mountPath: /appdata + name: appdata +``` + +## Bind Container + +After configuring the above details, navigate to the **Containers** page to bind the development container(**Dev Container**) for this app. Once done, you can start coding. + +![containers](/images/developer/develop/tutorial/create/bind.jpg) + +You can set a specified development environment for the bound **Dev Container**. Currently, DevBox supports `NodeJS`, `Golang`, and `Python` **Dev Container**. Let's bind a `NodeJS` **Dev Container** to the demo frontend container and a `Golang` **Dev Container** to the server container. + +We create a new **Dev Container** here. If you have previously created an unbound **Dev Container**, you can also choose an existing container for binding here. + +![bind container](/images/developer/develop/tutorial/create/bind-2.jpg) + +## Install App + +After binding the **Dev Container**, click **Install** in the upper right corner to install the development app into the system. Once the installation status shifts from `Processing` to `Running`, it indicates that the app is installed and ready for coding. + +![installing](/images/developer/develop/tutorial/create/installing.jpg) + +Then, navigate back to the **Containers** page. You'll notice that the **Open IDE button** is now enabled. Press this button to access the **Dev Container** and begin coding in the actual environment. + +![processing](/images/developer/develop/tutorial/create/success.jpg) diff --git a/docs/developer/develop/tutorial/note/frontend.md b/docs/developer/develop/tutorial/note/frontend.md new file mode 100644 index 000000000..7ac82ef8f --- /dev/null +++ b/docs/developer/develop/tutorial/note/frontend.md @@ -0,0 +1,74 @@ +# Develop Frontend Program + +## Preview App +After installing the app, you can preview the frontend of your application using the **Preview** button in **DevBox**. + +![preview](/images/developer/develop/tutorial/frontend/preview.jpg) + +## Open IDE + +When you open the frontend **Dev Contain IDE, you'll see the welcome page. From this point, the steps are like those for [backend development](backend.md). You can clone your frontend code using the Terminal. + +::: tip +In this example, the frontend and backend use the same code directory. So, after you've cloned the code for the backend, you don't need to do it again. +::: + +After cloning the code, if you are working on a Node project, you might need to make some configuration changes. + +- **Vite Configuration Changes** + + If your frontend project uses **Vite**, you need to add an **HMR** configuration. In development mode, **Vite** initiates a **WebSocket** to receive code reload notifications from the server. The default **WebSocket** port matches the server's startup port. However, if the development app uses an **Nginx proxy** it will operate on the default port 443. Therefore, some modifications are required. + + Modify the `vite.config.js` file as follows: + ```js + export default defineConfig({ + server: { + hmr: { + clientPort: 443, + }, + }, + }); + ``` +- **Nginx Configuration Changes** + + After setting up your project's development environment, you need to modify the Nginx configuration. Open `/etc/nginx/conf.d/dev/dev.conf` and make the necessary changes: + ```nginx + location / { + proxy_pass http://127.0.0.1:9000; + proxy_set_header Host $http_host; + proxy_set_header X-real-ip $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $http_connection; + proxy_set_header Accept-Encoding gzip; + } + ``` + + Then, reload Nginx: + ```sh + nginx -s reload + ``` +## Run Dev Mode +After completing the **Nginx** configuration, you can start your frontend program in dev mode and preview your APP in Olares. + +```sh +npm run dev +``` + +![frontend preview](/images/developer/develop/tutorial/frontend/preview2.jpg) + +If you need to set up a backend api proxy for the frontend, you can modify the proxy configuration in **Nginx**. + +```nginx +location /api/ { + proxy_pass http://127.0.0.1:9001; + proxy_set_header Host $http_host; + proxy_set_header X-real-ip $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $http_connection; + proxy_set_header Accept-Encoding gzip; +} +``` diff --git a/docs/developer/develop/tutorial/note/index.md b/docs/developer/develop/tutorial/note/index.md new file mode 100644 index 000000000..212d71eb7 --- /dev/null +++ b/docs/developer/develop/tutorial/note/index.md @@ -0,0 +1,16 @@ +# Create Your First Olares App + +You can learn how to develop an Olares app using DevBox through this tutorial. + +The tutorial shows how to make a simple [Note](https://github.com/beclab/olares-app-demo) tool. It demonstrates how to start from scratch and develop a complete Olares App. + +The tutorial includes three parts: + +1. [Create an App](./create.md)
+ This section provides a step-by-step guide on how to create an Olares App and set up the initial development environment. + +2. [Backend Development](./backend.md)
+ In this section, you'll learn how to use DevBox's IDE to develop the backend programs in `Golang` and provide API interfaces for the frontend. + +3. [Frontend Development](./frontend.md)
+ In this section, you'll learn how to use DevBox's IDE to develop frontend pages, using `NodeJS` as an example. \ No newline at end of file diff --git a/docs/developer/develop/tutorial/studio.md b/docs/developer/develop/tutorial/studio.md new file mode 100644 index 000000000..92c8acef8 --- /dev/null +++ b/docs/developer/develop/tutorial/studio.md @@ -0,0 +1,13 @@ +# Learn about DevBox + +At Olares, we provide a development tool called DevBox. It helps developers create applications for **Olares**. + +- Why is DevBox necessary for developers? + + Olares has many cloud-based features that are difficult to simulate in a standalone development environment. Furthermore, the unique sandbox system of **Olares** requires a real system environment for end-to-end testing. To simplify app simulation for developers and minimize system integration efforts during development, we provide the **DevBox**. **DevBox** is a quick, automatic toolset for creating app sandboxes. + +- What features does DevBox have? + + - In DevBox, you can build an app and generate a corresponding Olares Application Configuration* This deployment files can be modified, allowing you to port an existing app and deploy it to the Olares. During the modification process, you can continually attempt installation and resolve any issues that arise. Once the app passes your tests, you can download your Application Chart and submit it to the [Olares Market Repository](https://github.com/beclab/apps). + + - In addition to porting existing apps, you can also create a native Olares application in DevBox. DevBox provides an online development container where coders can work in a real environment, utilize other system interfaces, database clusters, and more. \ No newline at end of file diff --git a/docs/developer/install/activate-olares.md b/docs/developer/install/activate-olares.md new file mode 100644 index 000000000..07f008b5e --- /dev/null +++ b/docs/developer/install/activate-olares.md @@ -0,0 +1,38 @@ +--- +search: false +--- +## Activate Olares + +Use the Wizard URL and initial one-time password to activate. This process connects the Olares device with your Olares ID using LarePass. + +1. Enter the Wizard URL in your browser. You will be directed to the welcome page. Press any key to continue. + + ![Open wizard](/images/manual/get-started/open-wizard.png#bordered) +2. Enter the one-time password and click **Continue**. + + ![Enter password](/images/manual/get-started/wizard-enter-password.png#bordered) +3. Select the system language. + + ![Select language](/images/manual/get-started/select-language.png#bordered) +4. Activate Olares using LarePass app. + + a. Open LarePass app, and tap **Scan QR code** to scan the QR code on the Wizard page and complete the activation. + :::warning Same network required + To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network. + ::: + + ![Activate Olares](/images/manual/get-started/activate-olares.png#bordered) + + b. Reset the login password for Olares by following the on-screen instructions on LarePass. + + ::: tip Reactivate Olares with the same Olares ID + + If you have reinstalled Olares, the original instance becomes unavailable. To reactivate Olares with the same Olares ID: + + 1. Open LarePass on your phone, and you can see a red prompt: "No active Olares found". + 2. Tap **Learn more**, then **Reactivate** to enter the QR scan page. + 3. Tap **Scan QR code** to scan the QR code on the wizard page and activate Olares. + ::: + + +After successful setup, the LarePass app will automatically go to the home screen, and the Wizard will redirect you to the login page. \ No newline at end of file diff --git a/docs/developer/install/additional-installations.md b/docs/developer/install/additional-installations.md new file mode 100644 index 000000000..3dce3d467 --- /dev/null +++ b/docs/developer/install/additional-installations.md @@ -0,0 +1,21 @@ +--- +description: Installation guide for running Olares in containerized or virtual environments on macOS, Windows, PVE, Raspberry Pi, and more. Intended for development and testing only, not for production use. +--- + +# Additional installation options + +Additional installation options in this section are intended for **development or testing on special containerized or virtual environments** including Linux, macOS, Windows, PVE, or Raspberry Pi. + +:::tip Recommendation for production environment +Olares is optimized for Linux systems (Ubuntu or Debian). We recommend [installing Olares on Linux using script](../../manual/get-started/install-olares.md) to get the best performance and reliability for production use. +::: + +To run Olares, you must [create an Olares ID](../../manual/get-started/create-olares-id.md), and ensure that both the operating system and hardware meet the minimum requirements. + +Choose your preferred option to get started: +- [Install on Linx using Docker](linux-via-docker-compose.md) +- [Install on macOS](/developer/install/mac) +- [Install on Windows (WSL 2)](/developer/install/windows) +- [Install on PVE](/developer/install/pve) +- [Install on LXC](/developer/install/lxc) +- [Install on Raspberry Pi](/developer/install/raspberry-pi) diff --git a/docs/developer/install/cli/backups-backup.md b/docs/developer/install/cli/backups-backup.md new file mode 100644 index 000000000..c4622776d --- /dev/null +++ b/docs/developer/install/cli/backups-backup.md @@ -0,0 +1,84 @@ +--- +outline: [2, 3] +--- +# `backup` +:::warning +The `olares-cli backups download` command must be run first to install Restic. Otherwise, this command will return an error. +::: +## Synopsis +The `backup` subcommand allows you to back up data to the specified storage backend. It ensures your data is securely stored and can be restored whenever needed. + +```bash +olares-cli backups backup --path --repo-name [options] +``` + +## Common options +These options apply to all backends: + +| Option | Shorthand | Usage | Required | Default | +|---------------|-----------|----------------------------------------------|-------------------------|---------| +| `--help` | `-h` | Displays help information. | No | N/A | +| `--path` | | Specifies the directory to back up. | No | N/A | +| `--repo-name` | | Specifies the name of the backup repository. | No | N/A | + +## Backend-specific options +### Options for `cos` + +| Option | Shorthand | Usage | Required | Default | +|-----------------------|-----------|--------------------------------------------------------------------------------------------------|-------------------------|------------| +| `--access-key` | | Specifies the Access Key for Tencent COS. | No | N/A | +| `--endpoint` | | Specifies the Tencent COS endpoint, e.g., `https://cos.{region}.myqcloud.com/{bucket}/{prefix}`. | No | N/A | +| `--limit-upload-rate` | | Limits the upload speed to a maximum rate in KiB/s. | No | unlimited | +| `--secret-access-key` | | Specifies the Secret Access Key for Tencent COS. | No | N/A | | + +### Options for `fs` + +| Option | Shorthand | Usage | Required | Default | +|------------|-----------|----------------------------------------------------------------|-------------------------|---------| +| `--endpoint` | | Specifies the local directory where the backup will be stored. | No | N/A | + +### Options for `s3` + +| Option | Shorthand | Usage | Required | Default | +|-----------------------|-----------|---------------------------------------------------------------------------------------------|-------------------------|------------| +| `--access-key` | | Specifies the Access Key for Amazon S3. | No | N/A | +| `--endpoint` | | Specifies the Amazon S3 endpoint, e.g., `https://{bucket}.{region}.amazonaws.com/{prefix}`. | No | N/A | +| `--limit-upload-rate` | | Limits the upload speed to a maximum rate in KiB/s. | No | unlimited | +| `--secret-access-key` | | Specifies the Secret Access Key for Amazon S3. | No | N/A | | + +### Options for `space` + +| Option | Shorthand | Usage | Required | Default | +|-------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|------------| +| `--access-token` 1 | | Specifies the access token for Olares Space. | No | N/A | +| `--cloud-api-mirror` | | Specifies the cloud API mirror. | No | N/A | +| `--cloud-name` | | Specifies the cloud name of the Olares Space instance.
The cloud name can be retrieved using the [`region`](./backups-region.md) subcommand. | No | N/A | +| `--cluster-id` 2 | | Specifies the cluster ID where the backup will be stored. | No | N/A | +| `--limit-upload-rate` | | Limits the upload speed to a maximum rate in KiB/s. | No | unlimited | +| `--olares-did` 1 | | Specifies the Olares DID. | No | N/A | +| `--region-id` | | Specifies the region ID of the Olares Space instance.
The region ID can be retrieved using the [`region`](./backups-region.md) subcommand. | No | N/A | + +1. To retrieve the access token and Olares DID, inspect the payload of the network requests made by the Olares Space web interface after logging in. The `token` field corresponds to the access token, and the `userid` field corresponds to the Olares DID. + +2. To retrieve the cluster ID, use the following command: + ```bash + kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}' + ``` + +## Example +```bash +# Backup to Tencent COS +olares-cli backups backup cos --path /data --repo-name my_repo \ + --access-key YOUR_KEY \ + --secret-access-key YOUR_SECRET \ + --endpoint https://cos.region.myqcloud.com/bucket/prefix + +# Backup to Olares Space +olares-cli backups backup space --path /data --repo-name my_repo \ + --access-token YOUR_ACCESS_TOKEN \ + --cloud-api-mirror https://api-mirror.example.com \ + --cloud-name my_cloud \ + --region-id region_1 \ + --cluster-id cluster_12345 \ + --olares-did did:xyz123 +``` \ No newline at end of file diff --git a/docs/developer/install/cli/backups-download.md b/docs/developer/install/cli/backups-download.md new file mode 100644 index 000000000..8fe715843 --- /dev/null +++ b/docs/developer/install/cli/backups-download.md @@ -0,0 +1,19 @@ +# `download` + +## Synopsis +The `download` subcommand downloads the Restic dependency tool. Restic is required for performing backup and restore operations, as well as managing snapshots. + +```bash +olares-cli backups download [options] +``` +## Options + +| Option | Shorthand | Usage | Required | Default | +|--------------------|-----------|--------------------------------------------------------|-------------------------|--------------------| +| `--download-cdn-url`| | Specifies the CDN URL for downloading the Restic tool. | No | System default URL | +| `--help` | `-h` | Displays help information. | No | N/A | +## Example +```bash d +# Download Restic using a custom CDN URL +olares-cli backups download --download-cdn-url https://custom-cdn.example.com/restic +``` \ No newline at end of file diff --git a/docs/developer/install/cli/backups-region.md b/docs/developer/install/cli/backups-region.md new file mode 100644 index 000000000..d2ce03a28 --- /dev/null +++ b/docs/developer/install/cli/backups-region.md @@ -0,0 +1,27 @@ +# `region` + +## Synopsis +The `region` subcommand is used to retrieve the cloud name and region ID. It is specifically used when the storage backend is Olares Space. +```bash +olares-cli backups region space [options] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|-------------------------------|-----------|----------------------------------------------|-------------------------|---------| +| `--access-token` 1 | | Specifies the access token for Olares Space. | No | N/A | +| `--cloud-api-mirror` | | Specifies the cloud API mirror. | No | N/A | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--olares-did` 1 | | Specifies the Olares DID. | No | N/A | + +1. To retrieve the access token and Olares DID, inspect the payload of the network requests made by the Olares Space web interface after logging in. The `token` field corresponds to the access token, and the `userid` field corresponds to the Olares DID. + +## Example +```bash +# Query cloud name and region ID +olares-cli backups region space \ + --access-token YOUR_ACCESS_TOKEN \ + --cloud-api-mirror https://api-mirror.example.com \ + --olares-did did:xyz123 +``` \ No newline at end of file diff --git a/docs/developer/install/cli/backups-restore.md b/docs/developer/install/cli/backups-restore.md new file mode 100644 index 000000000..9ec145edd --- /dev/null +++ b/docs/developer/install/cli/backups-restore.md @@ -0,0 +1,84 @@ +--- +outline: [2, 3] +--- +# `restore` +:::warning +The `olares-cli backups download` command must be run first to install Restic. Otherwise, this command will return an error. +::: +## Synopsis +The `restore` subcommand allows you to restore data from a specified backup repository and snapshot to a target directory. + +```bash +olares-cli backups restore --path --repo-name --snapshot-id [options] +``` + +## Common options +These options apply to all backends: + +| Option | Shorthand | Usage | Required | Default | +|---------------|-----------|--------------------------------------------------------------|-------------------------|---------| +| `--help` | `-h` | Displays help information. | No | N/A | +| `--path` | | Specifies the directory to which data will be restored. | No | N/A | +| `--repo-name` | | Specifies the name of the backup repository to restore from. | No | N/A | +| `--snapshot-id`| | Specifies the snapshot ID to restore. | No | N/A | | + + +## Backend-specific options + +### Options for `cos` + +| Option | Shorthand | Usage | Required | Default | +|-------------------------|-----------|--------------------------------------------------------------------------------------------------|-------------------------|------------| +| `--access-key` | | Specifies the Access Key for Tencent COS. | No | N/A | +| `--endpoint` | | Specifies the Tencent COS endpoint, e.g., `https://cos.{region}.myqcloud.com/{bucket}/{prefix}`. | No | N/A | +| `--limit-download-rate` | | Limits the download speed to a maximum rate in KiB/s. | No | unlimited | +| `--secret-access-key` | | Specifies the Secret Access Key for Tencent COS. | No | N/A | + +### Options for `fs` + +| Option | Shorthand | Usage | Required | Default | +|-------------|-----------|-----------------------------------------------------------|-------------------------|---------| +| `--endpoint` | | Specifies the local directory where the backup is stored. | No | N/A | +| `--olares-id` | | Specifies the Olares ID. | No | N/A | + +### Options for `s3` + +| Option | Shorthand | Usage | Required | Default | +|-------------------------|-----------|---------------------------------------------------------------------------------------------|-------------------------|------------| +| `--access-key` | | Specifies the Access Key for Amazon S3. | No | N/A | +| `--endpoint` | | Specifies the Amazon S3 endpoint, e.g., `https://{bucket}.{region}.amazonaws.com/{prefix}`. | No | N/A | +| `--limit-download-rate` | | Limits the download speed to a maximum rate in KiB/s. | No | unlimited | +| `--secret-access-key` | | Specifies the Secret Access Key for Amazon S3. | No | N/A | + +### Options for `space` + +| Option | Shorthand | Usage | Required | Default | +|-------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|------------| +| `--access-token` 1 | | Specifies the access token for Olares Space. | No | N/A | +| `--cloud-api-mirror` | | Specifies the cloud API mirror. | No | N/A | +| `--cloud-name` | | Specifies the cloud name of the Olares Space instance.
The cloud name can be retrieved using the [`region`](./backups-region.md) subcommand. | No | N/A | +| `--cluster-id` 2 | | Specifies the cluster ID where the backup will be stored. | No | N/A | +| `--limit-download-rate` | | Limits the download speed to a maximum rate in KiB/s. | No | unlimited | +| `--olares-did` 1 | | Specifies the Olares DID. | No | N/A | +| `--region-id` | | Specifies the region ID of the Olares Space instance.
The region ID can be retrieved using the [`region`](./backups-region.md) subcommand. | No | N/A | + +1. To retrieve the access token and Olares DID, inspect the payload of the network requests made by the Olares Space web interface after logging in. The `token` field corresponds to the access token, and the `userid` field corresponds to the Olares DID. + +2. To retrieve the cluster ID, use the following command: + ```bash + kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}' + ``` + +## Example +```bash +# Restore the data from Tencent COS +olares-cli backups restore cos --path /data_restore --repo-name my_repo \ + --snapshot-id snapshot_12345 \ + --access-key YOUR_KEY \ + --secret-access-key YOUR_SECRET \ + --endpoint https://cos.region.myqcloud.com/bucket/prefix + +# Restore the data from local filesystem +olares-cli backups restore fs --path /data_restore --repo-name my_repo \ + --snapshot-id snapshot_12345 --endpoint /backup_repo +``` \ No newline at end of file diff --git a/docs/developer/install/cli/backups-snapshots.md b/docs/developer/install/cli/backups-snapshots.md new file mode 100644 index 000000000..383aa5fa1 --- /dev/null +++ b/docs/developer/install/cli/backups-snapshots.md @@ -0,0 +1,74 @@ +--- +outline: [2, 3] +--- +# `snapshots` +:::warning +The `olares-cli backups download` subcommand must be run first to install Restic. Otherwise, this command will return an error. +::: +## Synopsis +The `snapshots` subcommand lists all available snapshots for a specific backup repository. It supports multiple storage backends and provides the necessary options to authenticate and query snapshots. + +```bash +olares-cli backups snapshots --repo-name [options] +``` +## Common options +These options apply to all backends: + +| Option | Shorthand | Usage | Required | Default | +|---------------|-----------|-------------------------------------------------------|-------------------------|---------| +| `--help` | `-h` | Displays help information. | No | N/A | +| `--repo-name` | | Specifies the name of the backup repository to query. | No | N/A | + +## Backend-specific options + +### Options for `cos` + +| Option | Shorthand | Usage | Required | Default | +|---------------------|-----------|--------------------------------------------------------------------------------------------------|-------------------------|---------| +| `--access-key` | | Specifies the Access Key for Tencent COS. | No | N/A | +| `--endpoint` | | Specifies the Tencent COS endpoint, e.g., `https://cos.{region}.myqcloud.com/{bucket}/{prefix}`. | No | N/A | +| `--secret-access-key` | | Specifies the Secret Access Key for Tencent COS. | No | N/A | + +### Options for `fs` + +| Option | Shorthand | Usage | Required | Default | +|------------|-----------|----------------------------------------------------------------|-------------------------|---------| +| `--endpoint` | | Specifies the local directory where the backup will be stored. | No | N/A | + +### Options for `s3` + +| Option | Shorthand | Usage | Required | Default | +|---------------------|-----------|---------------------------------------------------------------------------------------------|-------------------------|---------| +| `--access-key` | | Specifies the Access Key for Amazon S3. | No | N/A | +| `--endpoint` | | Specifies the Amazon S3 endpoint, e.g., `https://{bucket}.{region}.amazonaws.com/{prefix}`. | No | N/A | +| `--secret-access-key` | | Specifies the Secret Access Key for Amazon S3. | No | N/A | + +### Options for `space` + +| Option | Shorthand | Usage | Required | Default | +|-------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|---------| +| `--access-token` 1 | | Specifies the access token for Olares Space. | No | N/A | +| `--cloud-api-mirror` | | Specifies the cloud API mirror. | No | N/A | +| `--cloud-name` | | Specifies the cloud name of the Olares Space instance.
The cloud name can be retrieved using the [`region`](./backups-region.md) subcommand. | No | N/A | +| `--cluster-id` 2 | | Specifies the cluster ID where the backup will be stored. | No | N/A | +| `--olares-did` 1 | | Specifies the Olares DID. | No | N/A | +| `--region-id` | | Specifies the region ID of the Olares Space instance.
The region ID can be retrieved using the [`region`](./backups-region.md) subcommand. | No | N/A | + +1. To retrieve the access token and Olares DID, inspect the payload of the network requests made by the Olares Space web interface after logging in. The `token` field corresponds to the access token, and the `userid` field corresponds to the Olares DID. + +2. To retrieve the cluster ID, use the following command: + ```bash + kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}' + ``` + +## Example +```bash +# List snapshots for Tencent COS +olares-cli backups snapshots cos --repo-name my_repo \ + --access-key YOUR_KEY \ + --secret-access-key YOUR_SECRET \ + --endpoint https://cos.region.myqcloud.com/bucket/prefix + +# List snapshots for local filesystem +olares-cli backups snapshots fs --repo-name my_repo --endpoint /backup_repo +``` \ No newline at end of file diff --git a/docs/developer/install/cli/backups.md b/docs/developer/install/cli/backups.md new file mode 100644 index 000000000..3f0c569d8 --- /dev/null +++ b/docs/developer/install/cli/backups.md @@ -0,0 +1,23 @@ +# `backups` +The `backups` command provides a set of tools to manage data backups, restores, and snapshots. It supports multiple storage backends, including Tencent COS, Amazon S3, the local filesystem, and Olares Space. + +## Subcommands + +| Subcommand | Description | +|-------------|----------------------------------------------------------------------------------------------------------| +| `download` | Downloads the Restic dependency tool. | +| `region` | Retrieves the cloud name and region ID. Specifically used only when the storage backend is Olares Space. | +| `backup` | Backups data to a specified storage backend. | +| `restore` | Restores data from a specified storage backend. | +| `snapshots` | Manages and views backup snapshots. | + +## Available backends + +The `` parameter specifies the storage backend for the `backup` and `restore` commands. Olares CLI supports the following backends: + +| Backend | Description | +|---------|---------------------------------------------------------------------------------------| +| `cos` | Tencent Cloud Object Storage (COS). Requires an access key, secret key, and endpoint. | +| `s3` | Amazon Simple Storage Service (S3). Requires an access key, secret key, and endpoint. | +| `fs` | Local filesystem. No credentials required. | +| `space` | Olares Space. Requires an access token. | \ No newline at end of file diff --git a/docs/developer/install/cli/change-ip.md b/docs/developer/install/cli/change-ip.md new file mode 100644 index 000000000..19f259801 --- /dev/null +++ b/docs/developer/install/cli/change-ip.md @@ -0,0 +1,34 @@ +# `change-ip` +:::warning When manually updating IP address is required +When Olares is deployed _inside_ a virtualized environment, such as macOS (via Minikube) or Windows (via WSL), a change in the host system's IP address (e.g., due to switching Wi-Fi networks) may cause Olares to become inaccessible. This happens because the NAT gateway and DNS configuration no longer match the new IP. In such cases, you need to manually update the IP address to ensure that Olares can route traffic correctly. + ::: + +## Synopsis +Change the local IP address for all Olares components. + +```bash +olares-cli change-ip [option] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|---------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--distribution` | `-d` | Sets the WSL distribution name. Only applicable on Windows. | No | `Ubuntu` | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--new-master-host` | | Specifies the new IP address of the master node on the worker node.
Only applicable for a multi-node Olares cluster. | No | N/A | +| `--profile` | `-p` | Sets the Minikube profile name. Only applicable on macOS. | No | `olares-0` | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Current version | + +## Examples +- For macOS: +```bash +# Specify the Minikube profile name and change the IP. +olares-cli change-ip --profile olares-0 +``` +- For Windows WSL: +```bash +# Specify the Linux distribution in WSL and change the IP. +olares-cli change-ip --distribution Ubuntu +``` \ No newline at end of file diff --git a/docs/developer/install/cli/download.md b/docs/developer/install/cli/download.md new file mode 100644 index 000000000..afc7b7242 --- /dev/null +++ b/docs/developer/install/cli/download.md @@ -0,0 +1,46 @@ +# `download` + +## Synopsis +The `download` command downloads the necessary packages and components required to install Olares on your local machine. It supports downloading components, checking the status of installation packages, and fetching the manifest file. + +```bash +olares-cli download [option] +``` + +## Subcommands + +| Name | Shorthand | Usage | Example | +|-------------|-----------|-------------------------------------------------------|----------------------------------------| +| `check` | | Checks the status of the Olares installation package. | `olares-cli download check` | +| `component` | `c` | Downloads Olares components. | `olares-cli download component` | +| `wizard` | `w` | Downloads the manifest file. | `olares-cli download wizard` | + +## Options + +| Option | Shorthand | Usage | Required | Default | +|--------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--download-cdn-url`| | Sets the CDN accelerated download URL in the format `https://example.cdn.com`. | No | System default URL | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--kube` | | Specifies the Kubernetes type.
Supported types are `k3s` and `k8s`. | No | `k3s` | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`). Defaults to the current version.
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Current version | + +## Examples +```bash +# Specifies the base directory where all downloaded components will be stored. +olares-cli download component -b /custom/path + +# Specifies a CDN-accelerated URL for downloading Olares components. +olares-cli download component --download-cdn-url https://my.cdn.com + +# Specifies the Kubernetes type for the installation. +olares-cli download component --kube k8s + +# Sets the path to the package manifest file. +olares-cli download component --manifest /custom/path/manifest.json + +# Specifies the version of Olares packages and components to download. +olares-cli download component -v 1.11.0 +``` + + diff --git a/docs/developer/install/cli/gpu.md b/docs/developer/install/cli/gpu.md new file mode 100644 index 000000000..245a2fc59 --- /dev/null +++ b/docs/developer/install/cli/gpu.md @@ -0,0 +1,54 @@ +# `gpu` + +## Synopsis + +The `gpu` command manages GPU-related operations, including installing, enabling, disabling, and uninstalling GPU drivers and related components, as well as checking the GPU status. + +```bash +olares-cli gpu [options] +``` + +:::info +- By default, the Olares installation script detects your GPU hardware and CUDA drivers, then configures and enables the GPU components and services automatically. +- Currently, only NVIDIA GPUs are supported. +::: + +## Subcommands + +| Subcommand | Description | +|-------------|--------------------------------------------------------------------------------------------------------------------------------------------| +| `install` | Installs GPU drivers and dependencies. | +| `enable` | Enables GPU functionality to support GPU-based applications. | +| `disable` | Disables GPU functionality, stopping support for GPU-based applications. | +| `uninstall` | Uninstalls GPU drivers and related components. | +| `status` | Displays the installed GPU driver version, CUDA version, and the status of GPU-related services. | + + +## Options + +| Option | Shorthand | Usage | Required | Default | +|------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------| +| `--base-dir`| `-b` | Specifies the base installation directory for the GPU components. | No | `$HOME/.olares` | +| `--version`| `-v` | Specifies the Olares version for GPU drivers and components.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Current version | +| `--help` | `-h` | Displays help information. | No | N/A | + +## Example + +```bash +# Install GPU drivers and dependencies to a specific directory +olares-cli gpu install --base-dir /home/olares/.olares --version 1.11.1-rc.4 + +# Enable GPU functionality +olares-cli gpu enable + +# View the status of GPU drivers and services +olares-cli gpu status + +# Disable GPU functionality +olares-cli gpu disable + +# Uninstall GPU drivers and components +olares-cli gpu uninstall +``` + + diff --git a/docs/developer/install/cli/info.md b/docs/developer/install/cli/info.md new file mode 100644 index 000000000..0c56b90f2 --- /dev/null +++ b/docs/developer/install/cli/info.md @@ -0,0 +1,14 @@ +# `info` + +## Synopsis +The `info` command displays general information about the installed Olares version. + +```bash +olares-cli info +``` + +## Flag + +| Name | Shorthand | Usage | +|----------|-----------|---------------------------| +| `--help` | `-h` | Display help information. | diff --git a/docs/developer/install/cli/install.md b/docs/developer/install/cli/install.md new file mode 100644 index 000000000..174b987a2 --- /dev/null +++ b/docs/developer/install/cli/install.md @@ -0,0 +1,18 @@ +# `install` + +## Synopsis +The `install` command installs Olares on your system. It supports various options to customize the installation process, such as specifying directories, Kubernetes types, or Minikube profiles. + +```bash +olares-cli install [option] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|------------------------------------------| +| `--base-dir`| `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--kube` | | Specifies the Kubernetes type.
Supported types are `k3s` and `k8s`. | No | `k3s` | +| `--profile`| `-p` | Sets the Minikube profile name. Only applicable on macOS. | No | `olares-0` | +| `--version`| `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Version installed in the `prepare` phase | \ No newline at end of file diff --git a/docs/developer/install/cli/logs.md b/docs/developer/install/cli/logs.md new file mode 100644 index 000000000..d4979a509 --- /dev/null +++ b/docs/developer/install/cli/logs.md @@ -0,0 +1,41 @@ +# `logs` + +## Synopsis +The `logs` command retrieves logs from Olares components and services found on the local machine. It searches for each component listed below, collects logs if the component is found, and skips it if not: + +* K3s/Kubelet logs +* Containerd logs +* JuiceFS logs +* Redis logs +* MinIO logs +* etcd logs +* olaresd logs +* Kubernetes pod info and logs +* Kubernetes node info + +```bash +olares-cli logs [option] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|------------------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------| +| `--components` | | Collects logs from specific components (comma-separated).
Supported values: `k3s`, `containerd`, `olaresd`, `kubelet`, `juicefs`, `redis`, `minio`, `etcd`, `NetworkManager`. | No | All detectable components | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--ignore-kube-errors` | | Ignores errors from `kubectl` commands (e.g., when Kubernetes API is unreachable) and continues collecting logs. | No | `false` | +| `--max-lines` | | Limits the maximum number of lines for each component's logs to prevent large log files. | No | `3000` | +| `--output-dir` | | Saves logs to the specified directory. Creates the directory if it does not exist. | No | `./olares-logs` | +| `--since` | | Fetches logs newer than a specified relative duration (e.g., `5s`, `2m`, `3h`). | No | `7d` | + +## Example +```bash +# Collect all logs with default settings +olares-cli logs + +# Collect logs for specific components +olares-cli logs --components k3s,redis,minio + +# Collect logs for the last 3 hours only +olares-cli logs --since 3h +``` \ No newline at end of file diff --git a/docs/developer/install/cli/node.md b/docs/developer/install/cli/node.md new file mode 100644 index 000000000..45ca3f639 --- /dev/null +++ b/docs/developer/install/cli/node.md @@ -0,0 +1,51 @@ +# `node` + +## Synopsis + +The `node` command manages node-related operations. + +```bash +olares-cli node [options] +``` + +## Subcommands + +| Subcommand | Description | +|--------------|-------------------------------------------------------------------------------------------------------------------------------| +| `masterinfo` | Retrieves system information about a target master node and checks whether the current node can join the cluster as a worker. | +| `add` | Adds the current node to an existing Olares cluster. The node's environment must already meet all prerequisites for Olares. | + +## Options + +| Option | Shorthand | Usage | Required | Default | +|---------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--master-host` | | Defines the IP address of the master node. | Yes | N/A | +| `--master-node-name` | | Specifies the Kubernetes node name of the master node. | No | N/A | +| `--master-ssh-user` | | Sets the remote Linux user name for SSH login to the master node. | No | `root` | +| `--master-ssh-password` | | Provides the password for the Linux user. | Yes if a non-root `master-ssh-user` is specified. | N/A | +| `--master-ssh-private-key-path` | | Specifies the path to the private SSH key for authenticating as the Linux user. | No | `/root/.ssh/id_rsa` | +| `--master-ssh-port` | | Sets the SSH service's listening port on the master node. | No | `22` | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Current version | +| `--help` | `-h` | Displays help information. | No | N/A | | + +## Example + +```bash +# Retrieve system information from a master node at IP 192.168.1.15 +olares-cli node masterinfo --master-host 192.168.1.15 + +# If a specific SSH key is required for authentication +olares-cli node masterinfo --master-host 192.168.1.15 --master-ssh-private-key-path /home/olares/.ssh/id_rsa + +# For non-root SSH users, specify the username and password +olares-cli node masterinfo --master-host 192.168.1.15 --master-ssh-user olares --master-ssh-password password123 + +# Add the current node to a cluster with the master node at IP 192.168.1.15 +olares-cli node add --master-host 192.168.1.15 + +# Specify a custom base directory for the installation +olares-cli node add --base-dir /custom/path --master-host 192.168.1.15 +``` + + diff --git a/docs/developer/install/cli/olares-cli.md b/docs/developer/install/cli/olares-cli.md new file mode 100644 index 000000000..77cf4b3fe --- /dev/null +++ b/docs/developer/install/cli/olares-cli.md @@ -0,0 +1,63 @@ +--- +outline: [2, 3] +--- +# Olares CLI + +:::warning Note +Use this version of Olares CLI if your Olares version is 1.12.X. +::: + +The Olares CLI is a versatile command-line tool designed to help developers and system administrators manage and troubleshoot Olares systems. It offers a wide range of features, from installation and configuration to resource management and diagnostics. + +With the Olares CLI, you can streamline tasks such as verifying system compatibility, downloading resources, managing nodes, collecting logs, and more. This guide provides an overview of the CLI's syntax and details the commands available for different operations. + +:::info Root privileges required +Most `olares-cli` commands require root privileges. Use the root user or prepend commands with `sudo`. +::: + +:::info Using Olares CLI with WSL +If you installed Olares using the WSL (Windows Subsystem for Linux) method, you need to use `olares-cli` inside the WSL environment. + +To enter the WSL environment, run the following command in PowerShell: + +```powershell +wsl -d Ubuntu +``` +::: + +## Syntax +The Olares CLI uses the following syntax: + +> `olares-cli command [subcommand] [option]` + +where +- `command`: Specifies the main operation you want to perform. For example, `olares-cli install`. +- `subcommand`: Further specifies the task for commands that support additional operations. For example, `wizard` or `component`. +- `option`: Optional arguments that modify the behavior of the `command`. Options include flags and options with arguments. + +Olares CLI allows you to temporarily override certain Olares default settings. Each option applies only to the command in which it is used. + +For example, if you use the `--base-dir` option with `olares-cli download wizard`, it will only affect the wizard downloading process and will not change the base directory for other commands, such as during the "install" phase. + +To get detailed help for any command, run `olares-cli help`. + +## Available CLI commands + +| Operation | Syntax | Description | +|--------------------|----------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| +| `gpu` | `olares-cli gpu [option]` | Manages GPU-related operations. | +| `info` | `olares-cli info [option]` | Displays general information about the operating system of the current device. | +| `node` | `olares-cli node [option]` | Manages node-related operations. | +| `backups` | `olares-cli backups [option]` | Manages backup-related operations. | +| `change-ip` | `olares-cli change-ip [option]` | Changes the IP address of the Olares OS. | +| `download` | `olares-cli download [option]` | Downloads specific resources. | +| `info` | `olares-cli info [option]` | Displays general information about the downloaded Olares OS. | +| `install` | `olares-cli install [option]` | Deploys system-level and user-level components of Olares. | +| `logs` | `olares-cli logs [option]` | Collects logs from Olares system components for debugging and troubleshooting. | +| `precheck` | `olares-cli precheck [option]` | Verifies whether the system environment meets all requirements for Olares installation. | +| `prepare` | `olares-cli prepare [option]` | Prepares the environment for the installation process, including setting up essential services and configurations of Olares. | +| `release` | `olares-cli release [option]` | Packages Olares installation resources for distribution or deployment. | +| `start` | `olares-cli start [option]` | Starts Olares services and components. | +| `stop` | `olares-cli stop [option]` | Stops Olares services and components. | +| `uninstall` | `olares-cli uninstall [option]` | Uninstalls Olares completely, or roll back the installation to a specific phase. | + diff --git a/docs/developer/install/cli/osinfo.md b/docs/developer/install/cli/osinfo.md new file mode 100644 index 000000000..a986d4a0b --- /dev/null +++ b/docs/developer/install/cli/osinfo.md @@ -0,0 +1,21 @@ +# `osinfo` + +## Synopsis + +The `osinfo` command provides detailed information about the operating system of the current device. Specifically, it retrieves and displays metadata such as `OS_TYPE`, `OS_PLATFORM`, `OS_ARCH`, `OS_VERSION`, `OS_KERNEL`, and `OS_INFO`. + +```bash +olares-cli osinfo [options] +``` + +## Subcommand + +| Subcommand | Description | +|------------|----------------------------------------------------------------------| +| `show` | Prints information about the operating system of the current device. | + +## Flag + +| Name | Short | Description | +|--------------|-------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--help` | `-h` | Displays help information. | \ No newline at end of file diff --git a/docs/developer/install/cli/precheck.md b/docs/developer/install/cli/precheck.md new file mode 100644 index 000000000..aae7c80ef --- /dev/null +++ b/docs/developer/install/cli/precheck.md @@ -0,0 +1,16 @@ +# `precheck` + +## Synopsis +The `precheck` command verifies whether the system environment satisfies all prerequisites required for Olares installation. + +```bash +olares-cli precheck [option] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|-----------------------------------| +| `--base-dir`| `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--version`| `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Current version | \ No newline at end of file diff --git a/docs/developer/install/cli/prepare.md b/docs/developer/install/cli/prepare.md new file mode 100644 index 000000000..2c15b1390 --- /dev/null +++ b/docs/developer/install/cli/prepare.md @@ -0,0 +1,25 @@ +# `prepare` + +## Synopsis +The `prepare` command sets up the environment required for Olares to function. This includes installing dependencies, importing container images, and starting the Olares daemon (`olaresd`). +```bash +olares-cli prepare [option] +``` + +## Options +| Option | Shorthand | Usage | Required | Default | +|--------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|-----------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--kube` | | Specifies the Kubernetes type.
Supported types are `k3s` and `k8s`. | No | `k3s` | +| `--profile` | `-p` | Sets the Minikube profile name. Only applicable on macOS. | No | `olares-0` | +| `--registry-mirrors`| `-r` | Specifies Docker container registry mirrors.
Multiple mirrors should be separated by commas. | No | N/A | +| `--with-juicefs` | | Configures JuiceFS as the root filesystem (rootfs) for Olares workloads instead of the local disk. | No | N/A | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Current version | + + +## Example +```bash +# Uses JuiceFS as the root filesystem +olares-cli prepare --with-juicefs=true +``` \ No newline at end of file diff --git a/docs/developer/install/cli/release.md b/docs/developer/install/cli/release.md new file mode 100644 index 000000000..44ba3f3a8 --- /dev/null +++ b/docs/developer/install/cli/release.md @@ -0,0 +1,19 @@ +# `release` + +## Synopsis +Build a release version based on a local Olares repository. This command should be run in the root directory of the Olares repository. + +```bash +olares-cli release [option] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|---------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|----------------------------------------| +| `--base-dir` | `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--download-cdn-url` | | Sets the CDN URL used for downloading checksums of dependencies and images. | No | `https://dc3p1870nn3cj.cloudfront.net` | +| `--extract` | `-e` | Extracts the release to the `--base-dir` after the build. Set to `false` if only the release file itself is needed. | No | `true` | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--ignore-missing-images` | | Ignores missing images when downloading checksums from the CDN.
Disable this only if no new images are added, as the build may fail if the image is not uploaded to the CDN yet. | No | `true` | +| `--version` | `-v` | Specifies the Olares version.
Version values follow the format `x.y.z` (e.g., `1.10.0`) or include a build date (e.g., `1.10.0-20241109`).
Refer to the [GitHub Releases page](https://github.com/beclab/Olares/releases) for available versions. | No | Current version | \ No newline at end of file diff --git a/docs/developer/install/cli/start.md b/docs/developer/install/cli/start.md new file mode 100644 index 000000000..451a64d50 --- /dev/null +++ b/docs/developer/install/cli/start.md @@ -0,0 +1,14 @@ +# `start` + +## Synopsis +The `start` command is used to start the Olares system, including its components and services, after it has been stopped. + +```bash +olares-cli start [option] +``` + +## Option + +| Name | Shorthand | Usage | +|------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--help` | `-h` | Displays help information. | diff --git a/docs/developer/install/cli/stop.md b/docs/developer/install/cli/stop.md new file mode 100644 index 000000000..6480d848c --- /dev/null +++ b/docs/developer/install/cli/stop.md @@ -0,0 +1,28 @@ +# `stop` + +## Synopsis +The `stop` command is used to stop the components of an installed (or partially installed) Olares system. + +```bash +olares-cli stop [option] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|--------------------|-----------|-----------------------------------------------------------------------------------------------------------|-------------------------|---------| +| `--check-interval` | | Specifies the interval between checks for remaining processes during shutdown (e.g., `5s`, `2m`, `3h`). | No | `10s` | +| `--help` | `-h` | Displays help information. | No | N/A | +| `--timeout` | | Sets the maximum time to wait for a graceful shutdown before using SIGKILL (e.g., `5s`, `2m`, `3h`). | No | `1m` | + +## Example +```bash +# Stop the Olares system +olares-cli stop + +# Adjust the timeout for shutdown +olares-cli stop --timeout 2m + +# Specify a custom check interval +olares-cli stop --check-interval 5s +``` \ No newline at end of file diff --git a/docs/developer/install/cli/uninstall.md b/docs/developer/install/cli/uninstall.md new file mode 100644 index 000000000..e39ea6f20 --- /dev/null +++ b/docs/developer/install/cli/uninstall.md @@ -0,0 +1,19 @@ +# `uninstall` + +## Synopsis +Uninstall Olares from your machine. + +```bash +olares-cli uninstall [option] +``` + +## Options + +| Option | Shorthand | Usage | Required | Default | +|-------------|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|--------------------------------| +| `--all` | | Uninstalls Olares completely, including dependencies installed during the "prepare" phase. | No | Not applicable | +| `--base-dir`| `-b` | Sets the base directory for Olares. | No | `$HOME/.olares` | +| `--help` | `-h` | Displays help information. | No | Not applicable | +| `--phase` | | Uninstalls Olares from a specific phase and revert to the previous one.
For example, `--phase install` removes tasks performed during the "install" phase, reverting the system to the "prepare" stage. | No | `install` | +| `--quiet` | | Enables quiet mode (suppress output). | No | `false` | +| `--version` | `-v` | Specifies the Olares version to uninstall.
Use `olares-cli info` to check the downloaded version first. | No | Current version | \ No newline at end of file diff --git a/docs/developer/install/environment-variables.md b/docs/developer/install/environment-variables.md new file mode 100644 index 000000000..53d96dae5 --- /dev/null +++ b/docs/developer/install/environment-variables.md @@ -0,0 +1,198 @@ +--- +outline: [2, 3] +description: Environment variables available in Olares for customizing networking, authentication, GPU support and other features. Includes configuration examples and specifications. +--- +# Olares environment variables + +Olares provides a highly customizable installation process through the use of environment variables. These variables can override default settings, enabling advanced configurations to suit your specific requirements. + +## Usage examples + +To customize the installation process, you can set the environment variables before running the installation command. For example: + +```bash +# Specify Kubernetes (k8s) instead of k3s +export KUBE_TYPE=k8s \ +&& curl -sSfL https://olares.sh | bash - +``` +Or, if you have already downloaded the installation script `install.sh`: + +```bash +# Specify Kubernetes (k8s) instead of k3s +export KUBE_TYPE=k8s && bash install.sh +``` +Both methods achieve the same result. The environment variable `KUBE_TYPE` will be passed to the script, and the script will use it to modify its behavior. + +## Environment variables reference + +The section lists all the environment variables, along with their default values, optional values, and descriptions. Configure them as needed. + +### `CLOUDFLARE_ENABLE` +Specifies whether to enable the Cloudflare proxy. +- **Valid values**: + - `0` (disable) + - `1` (enable) +- **Default**: `0` + +### `DID_GATE_URL` +Specifies the endpoint for the DID gateway. +- **Valid values**: + - `https://did-gate-v3.bttcdn.com` + - `https://did-gate-v3.api.jointerminus.cn/` (recommended for better connectivity in mainland China) +- **Default**: `https://did-gate-v3.bttcdn.com` + +### `FIREBASE_PUSH_URL` +Specifies the endpoint for Firebase push services. +- **Valid values**: + - `https://firebase-push-test.bttcdn.com/v1/api/push` + - `https://firebase-push-test.api.jointerminus.cn/v1/api/push` (recommended for better connectivity in mainland China) +- **Default**: `https://firebase-push-test.bttcdn.com/v1/api/push` + +### `FRP_AUTH_METHOD` +Sets the FRP authentication method. +- **Valid values**: + - `jws` + - `token` (requires `FRP_AUTH_TOKEN`) + - (empty) – No authentication +- **Default**: `jws` + +### `FRP_AUTH_TOKEN` +Specifies the token for FRP communication (required if `FRP_AUTH_METHOD=token`). +- **Valid values**: Any non-empty string +- **Default**: None + +### `FRP_ENABLE` +Specifies whether to enable FRP for internal network tunneling. Requires additional FRP-related variables if using a custom server. +- **Valid values**: + - `0` (disable) + - `1` (enable) +- **Default**: `0` + +### `FRP_LIST_URL` +Specifies the endpoint for the Olares FRP information service. +- **Valid values**: + - `https://terminus-frp.snowinning.com` + - `https://terminus-frp.api.jointerminus.cn` (recommended for better connectivity in mainland China) +- **Default**: `https://terminus-frp.snowinning.com` + +### `FRP_PORT` +Specifies the FRP server's listening port. +- **Valid values**: An integer in the range `1–65535` +- **Default**: `7000` (if not set or set to `0`) + +### `JUICEFS` +Installs [JuiceFS](https://juicefs.com/) alongside Olares. +- **Valid values**: `1` +- **Default**: None (does not install JuiceFS if not set) + +### `KUBE_TYPE` +Determines the Kubernetes distribution to install. +- **Valid values**: + - `k8s` (full Kubernetes) + - `k3s` (lightweight Kubernetes) +- **Default**: `k3s` + +### `LOCAL_GPU_ENABLE` +Specifies whether to enable GPU support and install related drivers. +- **Valid values**: + - `0` (disable) + - `1` (enable) +- **Default**: `0` + +### `LOCAL_GPU_SHARE` +Specifies whether to enable GPU sharing. Applies only if GPU is enabled. +- **Valid values**: + - `0` (disable) + - `1` (enable) +- **Default**: `0` + +### `MARKET_PROVIDER` +Specifies the backend domain used by the application marketplace (Market). +- **Valid values**: + - `appstore-server-prod.bttcdn.com` + - `appstore-china-server-prod.api.jointerminus.cn` (recommended for better connectivity in mainland China) +- **Default**: `appstore-server-prod.bttcdn.com` + +### `NVIDIA_CONTAINER_REPO_MIRROR` +Specifies the APT repository mirror for installing NVIDIA Container Toolkit. +- **Valid values**: + - `nvidia.github.io` + - `mirrors.ustc.edu.cn` (recommended for better connectivity in mainland China) +- **Default**: `nvidia.github.io` + +### `OLARES_SPACE_URL` +Specifies the endpoint for the Olares Space service. +- **Valid values**: + - `https://cloud-api.bttcdn.com/` + - `https://cloud-api.api.jointerminus.cn/` (recommended for better connectivity in mainland China) +- **Default**: `https://cloud-api.bttcdn.com/` + +### `PREINSTALL` +Runs only the pre-installation phase (system dependency setup) without proceeding to the full Olares installation. +- **Valid values**: `1` +- **Default**: None (performs full installation if not set) + +### `PUBLICLY_ACCESSIBLE` +Explicitly specifies that this machine is accessible publicly on the internet, and a reverse proxy should not be used. +- **Valid values**: + - `0` (false) + - `1` (true) +- **Default**: `0` + + +### `REGISTRY_MIRRORS` +Specifies a custom Docker registry mirror for faster image pulls. +- **Valid values**: `https://mirrors.joinolares.cn` or any other valid URL +- **Default**: `https://registry-1.docker.io` + +### `TAILSCALE_CONTROLPLANE_URL` +Specifies the endpoint for the Olares Tailscale control-plane service. +- **Valid values**: + - `https://controlplane.snowinning.com` + - `https://controlplane.api.jointerminus.cn` (recommended for better connectivity in mainland China) +- **Default**: `https://controlplane.snowinning.com` + +### `TERMINUS_CERT_SERVICE_API` +Specifies the endpoint for the Olares HTTPS certificate service. +- **Valid values**: + - `https://terminus-cert.snowinning.com` + - `https://terminus-cert.api.jointerminus.cn` (recommended for better connectivity in mainland China) +- **Default**: `https://terminus-cert.snowinning.com` + +### `TERMINUS_DNS_SERVICE_API` +Specifies the endpoint for the Olares DNS service. +- **Valid values**: + - `https://terminus-dnsop.snowinning.com` + - `https://terminus-dnsop.api.jointerminus.cn` (recommended for better connectivity in mainland China) +- **Default**: `https://terminus-dnsop.snowinning.com` + +### `TERMINUS_IS_CLOUD_VERSION` +Marks the machine explicitly as a cloud instance. +- **Valid values**: `true` +- **Default**: None + +### `TERMINUS_OS_DOMAINNAME` +Sets the domain name before installation to skip the interactive prompt. +- **Valid values**: Any valid domain name +- **Default**: None (prompts for domain name if not set) + +### `TERMINUS_OS_EMAIL` +Specifies the email address to use instead of a generated one. +- **Valid values**: Any valid email address +- **Default**: None (a temporary email is generated if not set) + +### `TERMINUS_OS_PASSWORD` +Specifies the password to use instead of a generated one. +- **Valid values**: A valid password with 6–32 characters +- **Default**: A randomly generated 8-character password + +### `TERMINUS_OS_USERNAME` +Specifies the username before installation to skip the interactive prompt. +- **Valid values**: Any valid username (2–250 characters, excluding reserved keywords) +- **Default**: None (prompts for username if not set) +- **Validation**: Reserved keywords include `user`, `system`, `space`, `default`, `os`, `kubesphere`, `kube`, `kubekey`, `kubernetes`, `gpu`, `tapr`, `bfl`, `bytetrade`, `project`, `pod` + +### `TOKEN_MAX_AGE` +Sets the maximum validity period for a token (in seconds). +- **Valid values**: Any integer (in seconds) +- **Default**: `31536000` (365 days) \ No newline at end of file diff --git a/docs/developer/install/index.md b/docs/developer/install/index.md new file mode 100644 index 000000000..b8bcc610d --- /dev/null +++ b/docs/developer/install/index.md @@ -0,0 +1,13 @@ +--- +description: Technical overview of Olares deployment including system architecture, setup processes, environment configuration, CLI capabilities and version management. Key concepts for developers working with Olares. +--- +# Olares installation deep-dive + +This section provides in-depth information, command references, and instructions to help you explore, learn, and customize your Olares installation. + +- [Olares installation overview](installation-process.md): Learn how Olares is installed from the perspectives of overall architecture and core components. +- [Olares installation breakdown](installation-process.md): Explore the Olares installation process in detail, broken down into four key phases. +- [Olares Home introduction](olares-home.md): Understand the structure of the base installation directory. +- [Olares environment variables reference](environment-variables.md): Find the right environment variables for you to customize the installation. +- [Olares CLI reference](./index.md): Uses the Olares CLI for advanced customization and troubleshooting during installation. +- [Olares versioning](versioning.md): Learn versioning rules, release types, branch management practices, and upgrade guidelines of Olares. \ No newline at end of file diff --git a/docs/developer/install/install-and-activate-olares.md b/docs/developer/install/install-and-activate-olares.md new file mode 100644 index 000000000..70aff6294 --- /dev/null +++ b/docs/developer/install/install-and-activate-olares.md @@ -0,0 +1,20 @@ +--- +search: false +--- +## Install and activate Olares +:::warning Same network required +To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network. +::: + +1. Open LarePass, on your account activation page, tap **Discover nearby Olares**. LarePass will list the detected Olares instances in the same network. +2. Select the target Olares device from the list and tap **Install now**. +3. When the installation completes, tap **Activate now**. Olares will enter the activation process, including initial configuration and network setup. +4. Follow the on-screen instructions to reset the login password for Olares, then tap **Complete**. + +![Activate Olares via LarePass](/images/manual/get-started/activate-olares-mdns.png#bordered) + +Once activation is complete, LarePass will display the desktop address of your Olares device, such as `https://desktop.marvin123.olares.com`. + +![Access Olares via browser](/images/manual/get-started/access-olares-via-browser.png#bordered){width=30%} + + \ No newline at end of file diff --git a/docs/developer/install/installation-overview.md b/docs/developer/install/installation-overview.md new file mode 100644 index 000000000..f7034c0e9 --- /dev/null +++ b/docs/developer/install/installation-overview.md @@ -0,0 +1,96 @@ +--- +outline: [2, 3] +description: Core architecture of Olares deployment across native system layer, Kubernetes orchestration and containerized services. Technical insights into how Olares layers interact. +--- +# Olares installation architecture + +This document provides a high-level overview of the Olares installation process, focusing on its overall architecture and core components. It is intended for system administrators and developers who need a foundational understanding of how Olares operates and is installed. + +## Three layers of Olares installation +The Olares installation is structured into three key layers: + +- **Native layer**: Manages Linux system configurations and installs essential environment dependencies. +- **Container orchestration layer**: Deploys the Kubernetes cluster to enable automated service management and scaling. +- **Containerization layer**: Launches containerized core system services and user applications, providing the final runtime environment. + +The installation process is managed by the `olares-cli` tool. This command-line tool orchestrates the installation, configuration, and lifecycle management of all components. + +![Install arch](/images/developer/install/olares-install.png) + +::: tip +To understand the detailed installation process phase-by-phase, refer to [Olares installation breakdown](installation-process.md). +::: + +## Native layer +The Olares installation process begins at the native layer, ensuring that the underlying Linux environment supports distributed storage, container runtimes, and Kubernetes cluster management. + +This layer's configuration includes core Linux system settings, file system initialization, container runtime installation, and deployment of critical system services. + +### Environment configuration + +The installation first configures the basic Linux installation environment. This includes setting up Domain Name System (DNS), Secure Shell (SSH), and Network Time Protocol (NTP) services to ensure time synchronization and remote management capabilities. + +Additionally, necessary dependencies such as the GNU Compiler Collection (GCC) and Network Tools (net-tools) are installed to ensure a robust runtime environment. + +### File system configuration + +The root file system (rootfs) is used to store and access system core components and user data. Olares supports the following two file systems based on deployment needs: + +- **LocalFS** (default): Uses the local Linux disk for storage. It is ideal for single-node deployments that require high data throughput without the need for network sharing. + +- **JuiceFS**: Provides a distributed file system for multi-node cluster. File data are stored in locally installed MinIO instances or remote storage buckets such as Amazon S3. This setup allows different storage nodes to share a unified storage view. + + :::tip Enable JuiceFS + JuiceFS and MinIO are not installed by default. To enable them, set the necessary [environment variables](environment-variables.md#juicefs) or use `olares-cli` with JuiceFS-specific flags. + ::: + +### Container runtime: containerd +Olares uses containerd, a lightweight container runtime, for containerized deployments. Its features include: +- **Container image management**: + - Downloads packaged container images from the Content Delivery Network (CDN) + - Imports them into containerd during the "prepare" phase + - Starts the images as container processes during the "install" phase +- **Container lifecycle management**: Starts, stops, restarts, and monitors containerized application services. + +::: tip Compatibility issue +If containerd is already installed on your machine (for example, as part of Docker), it may cause compatibility issues with the containerd used by Olares. Please uninstall the existing containerd before installing Olares. +::: + +### System daemon: olaresd +olaresd is the system daemon that runs in the background, providing essential management functionalities such as: +- **Automated configuration updates**: Automatically adjusts configurations when system changes (e.g. IP changes) are detected. +- **Remote system management**: Executes remote system operations, such as Olares installation and activation, based on requests issued from the LarePass client or `olares-cli`. + +### CUDA support +To enable GPU acceleration for local AI models and applications, Olares supports automatic installation of the CUDA toolkit and drivers through [`olares-cli`](./cli/gpu.md). + +## Container orchestration layer +The container orchestration layer integrates system components into an efficient runtime environment using Kubernetes. + +### Roles of Kubernetes +Kubernetes serves as the backbone of the container orchestration layer, providing automated deployment, operation, scaling, and management of multi-component services. + +Compared to tools like Docker Compose or Docker Swarm, Kubernetes offers: +- High scalability and production-grade reliability. +- Robust community support and a rich ecosystem for integrating applications via Helm Charts, Operators, and Custom Resource Definitions (CRDs). + +### Kubernetes options in Olares +Olares supports the following Kubernetes setups: +- **K3s** (default): A lightweight Kubernetes distribution optimized for resource efficiency on local hardware. +- **Kubernetes**: The full-featured Kubernetes distribution for advanced or custom deployments. +- **minikube** (macOS only): A tool that sets up a single-node Kubernetes cluster, ensuring consistent features and user experience. + +## Containerization layer + +The containerization layer is where Olares' components and applications come together to provide the system's full functionality. All Olares components and user applications run within containers, with the full lifecycle managed via Kubernetes. This ensures that the system remains efficient, stable, and scalable. + +Once Olares is installed and activated, you can view the running containers through a graphical user interface provided by the Control Hub app: + +![View running pods in Control Hub](/images/developer/install/running-pods.png#bordered){width=90%} + +## Learn more + +- [Olares installation breakdown](installation-process.md) +- [Olares Home](olares-home.md) +- [Olares CLI](../install/cli/olares-cli.md) +- [Olares environment variables](environment-variables.md) \ No newline at end of file diff --git a/docs/developer/install/installation-process.md b/docs/developer/install/installation-process.md new file mode 100644 index 000000000..d989b5ddb --- /dev/null +++ b/docs/developer/install/installation-process.md @@ -0,0 +1,328 @@ +--- +outline: [2, 3] +description: Technical breakdown of Olares deployment phases covering system validation, component downloads, environment preparation and service deployment. In-depth look at each installation stage. +--- +# Olares installation breakdown +This document explains the Olares installation process from the perspective of its four main phases. It is aimed at developers and system administrators who want to understand the installation in detail, including the underlying commands, configurations, and logic behind each phase. + +## Four phases of installation +The Olares installation process is divided into four phases, each ensuring a smooth and stable setup: + +- **Precheck**: Verifies that the system environment meets all prerequisites for Olares installation. +- **Download**: Retrieves all necessary files, dependencies, and container images for the installation. +- **Prepare**: Configures the operating system and system services to create an environment ready for Kubernetes and Olares components. +- **Install**: Deploys Kubernetes, integrates KubeSphere, and installs core Olares services and applications. + +## Precheck phase + +The precheck phase focuses on verifying that your system meets the necessary requirements for installing Olares. The `olares-cli precheck` command is used to run a series of validation checks. Any issues identified during this phase must be resolved before continuing with the installation. + +Key checks include: +- Checks the compatibility with the operating system type, version, and CPU architecture +- Confirms that the system uses `Systemd` as its initialization process +- Ensures required ports that Olares needs to expose are available +- Verifies that no conflicting container runtime is installed + +If the precheck fails, you'll see a warning like this: + + ![Precheck](/images/developer/install/precheck.png) + +In this example: +- Port `9100` required by Olares is already in use. +- An existing container runtime is detected in the system. + +You must resolve these issues before proceeding. + +## Download phase + +The download phase retrieves the necessary wizard files, system dependencies, and container images required for Olares installation. + +### Download the wizard file + +The wizard file is a metadata package that contains download URLs and configuration details for all Olares components. It is the first file retrieved during this phase, as it provides critical information for the subsequent downloads. + +By default, the wizard file is stored in: + +`HOME/.olares/versions/` + +where: +- `$HOME/.olares` is the base directory for Olares. +- `` refers to the version number of Olares (e.g. `1.12.0-20241215`). + +:::details Example script output +```bash +➜ ~ ./install.sh +the KUBE_TYPE env var is not set, defaulting to "k3s" +olares-cli already installed and is the expected version + +downloading installation wizard... + +current: root +2024-12-17T18:01:19.501+0800 [Job] [Download Installation Wizard] start ... +2024-12-17T18:01:19.501+0800 [Module] GreetingsModule +Greetings, Olares +2024-12-17T18:01:19.502+0800 [A] ubuntu: Greetings success (611.77µs) +2024-12-17T18:01:19.502+0800 [Module] DownloadInstallWizard +/home/keven/.olares/versions/v1.12.0-20241215/.env +/home/keven/.olares/versions/v1.12.0-20241215/wizard/config/account/Chart.yaml +``` +::: +### Download components and container images +Once the wizard file has been downloaded, the script retrieves all necessary dependencies and container images. These files are stored in: +- `$HOME/.olares/pkg` for dependency packages. +- `$HOME/.olares/image` for container images. + +This storage structure allows reusing stable components across multiple versions to avoid redundant downloads. + +:::details Example script output +```bash +downloading installation packages... + +current: root +2024-12-17T19:41:36.847+0800 [Job] [Download Installation Package] start ... +2024-12-17T19:41:36.847+0800 [Module] GreetingsModule +Greetings, Olares +2024-12-17T19:41:36.848+0800 [A] ubuntu: Greetings success (512.711µs) +2024-12-17T19:41:36.848+0800 [Module] GenerateOlaresUninstallScript +2024-12-17T19:41:36.879+0800 [A] LocalHost: GenerateOlaresUninstallScript success (31.279866ms) +2024-12-17T19:41:36.879+0800 [Module] PackageDownloadModule +2024-12-17T19:41:36.879+0800 checking local cache ... +2024-12-17T19:41:44.614+0800 5 out of 177 files need to be downloaded +2024-12-17T19:41:44.615+0800 (1/5) downloading package olaresd, file: olaresd-v0.0.50.tar.gz +2024-12-17T19:41:51.814+0800 (2/5) downloading image calico/kube-controllers:v3.23.2, file: 521564c4b60ae73c78899b7b40ae655e.tar.gz +... +``` +::: +## Prepare phase + +The prepare phase configures the system environment to support Kubernetes, container images, and Olares services. + +This phase involves three main tasks: +- Configure the system +- Set up the container runtime +- Install the system daemon + +### Configure system +The installation script configures the Linux environment to meet Olares' requirements. These configurations include: +- Adjusts DNS, NTP, and SSH services to ensure proper network functionality and time synchronization. +- Installs essential dependencies (e.g., curl, net-tools, gcc, make) via `apt`. + +:::details Example script output +```bash +preparing installation environment... + +current: root +2024-12-17T19:46:39.517+0800 [Job] [Prepare the System Environment] start ... +2024-12-17T19:46:39.517+0800 [Module] PreCheckOs +2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckSupport success (29.999µs) +2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckPortsBindable success (144.035µs) +2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckNoConflictingContainerd success (31.009µs) +2024-12-17T19:46:39.517+0800 [A] ubuntu: PatchAppArmor skipped (7.677µs) +2024-12-17T19:46:39.517+0800 [A] ubuntu: RaspbianCheck success (5.796µs) +2024-12-17T19:46:39.517+0800 [A] ubuntu: CorrectHostname success (5.363µs) +nameserver +nameserver +2024-12-17T19:46:41.921+0800 [A] ubuntu: DisableLocalDNS success (2.40336625s) +2024-12-17T19:46:41.921+0800 [INFO] installing and configuring OS dependencies ... +2024-12-17T19:46:41.921+0800 [Module] InstallDeps +Hit:1 http://security.ubuntu.com/ubuntu jammy-security InRelease +Hit:2 https://download.docker.com/linux/ubuntu jammy InRelease +Hit:3 http://hk.archive.ubuntu.com/ubuntu jammy InRelease +... +``` +::: +### Set up container runtime +The container runtime is a critical component for running containerized applications. During this step, the installation script: +- Installs and start the previously downloaded dependencies +- Installs containerd on the system and start the service +- Imports the downloaded container images into containerd + +:::details Example script output +```bash +2024-12-17T19:47:37.510+0800 [Module] InstallContainerModule(k3s) +2024-12-17T19:47:37.518+0800 [A] ubuntu: ZfsMountReset skipped (7.321811ms) +2024-12-17T19:47:37.525+0800 [A] ubuntu: CreateZfsMount skipped (7.322591ms) +2024-12-17T19:47:38.188+0800 [A] ubuntu: SyncContainerd success (662.643982ms) +2024-12-17T19:47:38.368+0800 [A] ubuntu: SyncCrictlBinaries success (179.758334ms) +2024-12-17T19:47:38.399+0800 [A] ubuntu: GenerateContainerdService success (31.410118ms) +2024-12-17T19:47:38.451+0800 [A] ubuntu: GenerateContainerdConfig success (52.047108ms) +2024-12-17T19:47:38.505+0800 [A] ubuntu: GenerateCrictlConfig success (53.760209ms) +2024-12-17T19:47:38.857+0800 [A] ubuntu: EnableContainerd success (352.128078ms) +2024-12-17T19:47:38.857+0800 [Module] PreloadImages +2024-12-17T19:47:41.665+0800 (1/145) imported image: rancher/mirrored-pause:3.6, time: 194.363948ms +... +``` +::: +### Install system daemon +The Olares system daemon, olaresd, is then installed and started to monitor the system and automatically perform maintenance tasks. + +:::details Example script output +```bash +024-12-17T19:52:31.862+0800 [A] ubuntu: GenerateOlaresdEnv success (23.829684ms) +2024-12-17T19:52:31.862+0800 template OlaresdService result: [Unit] +Description=olaresd +After=network.target +StartLimitIntervalSec=0 + +[Service] +User=root +EnvironmentFile=/etc/systemd/system/olaresd.service.env +ExecStart=/usr/local/bin/olaresd +RestartSec=10s +LimitNOFILE=40000 +Restart=always + +[Install] +WantedBy=multi-user.target + +2024-12-17T19:52:31.885+0800 [A] ubuntu: GenerateOlaresdService success (23.050958ms) +2024-12-17T19:52:32.033+0800 [A] ubuntu: EnableOlaresdService success (147.987242ms) +... +``` +::: +## Install phase +The install phase brings all system components online and ensures the runtime environment is fully operational. + +During this phase, the script primarily completes the following tasks: +- Deploy Kubernetes. +- Integrate KubeSphere for cloud-native management and observability. +- Configure the Olares account. +- Deploy and start built-in apps and services. + +### Deploy Kubernetes + +Kubernetes is the backbone of the Olares system. During this step, the installation script: +1. Starts the etcd database. +2. Starts and configures K3s. +3. Installs a Container Network Interface (CNI) plugin for cluster networking. +4. Copies the `kubeconfig` file to the current user's directory, enabling interaction with the cluster via `kubectl`. + +K3s is the default Kubernetes distribution for Olares due to its lightweight design and ease of use. However, kubernetes is also available for advanced or custom setups. + +On macOS, the scripts uses minikube, which will skip the above step. + +:::details Example script output +```bash +[certs] Generating "ca" certificate and key +[certs] admin-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16] +[certs] member-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16] +[certs] node-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16] +2024-12-17T19:52:36.957+0800 [A] LocalHost: GenerateETCDCerts success (263.237575ms) +2024-12-17T19:52:37.263+0800 [A] ubuntu: SyncCertsFile success (306.213676ms) +2024-12-17T19:52:37.264+0800 [A] ubuntu: SyncCertsFileToMaster skipped (20.351µs) +2024-12-17T19:52:37.264+0800 [Module] InstallETCDBinaryModule +2024-12-17T19:52:37.698+0800 [A] ubuntu: InstallETCDBinary success (434.014395ms) +2024-12-17T19:52:37.728+0800 [A] ubuntu: GenerateETCDService success (30.732882ms) +2024-12-17T19:52:37.728+0800 [A] ubuntu: GenerateAccessAddress success (23.491µs) +2024-12-17T19:52:37.728+0800 [Module] ETCDConfigureModule +2024-12-17T19:52:37.728+0800 [A] ubuntu: ExistETCDHealthCheck skipped (9.903µs) +2024-12-17T19:52:37.753+0800 [A] ubuntu: GenerateETCDConfig success (24.125665ms) +2024-12-17T19:52:37.773+0800 [A] ubuntu: AllRefreshETCDConfig success (20.321235ms) +2024-12-17T19:52:40.048+0800 [A] ubuntu: RestartETCD success (2.274541565s) +2024-12-17T19:52:40.068+0800 [A] ubuntu: AllETCDNodeHealthCheck success (20.251062ms) +2024-12-17T19:52:40.094+0800 [A] ubuntu: RefreshETCDConfigToExist success (26.207599ms) +2024-12-17T19:52:40.129+0800 [A] ubuntu: AllETCDNodeHealthCheck success (34.462881ms) +2024-12-17T19:52:40.129+0800 [Module] ETCDBackupModule +2024-12-17T19:52:40.185+0800 [A] ubuntu: BackupETCD success (56.639923ms) +2024-12-17T19:52:40.230+0800 [A] ubuntu: GenerateBackupETCDService success (44.727929ms) +2024-12-17T19:52:40.273+0800 [A] ubuntu: GenerateBackupETCDTimer success (42.839457ms) +2024-12-17T19:52:40.396+0800 [A] ubuntu: EnableBackupETCDService success (122.621074ms) +2024-12-17T19:52:40.396+0800 [Module] InstallKubeBinariesModule +2024-12-17T19:52:41.188+0800 [A] ubuntu: SyncKubeBinary(k3s) success (791.866964ms) +2024-12-17T19:52:41.218+0800 [A] ubuntu: GenerateK3sKillAllScript success (30.442837ms) +2024-12-17T19:52:41.253+0800 [A] ubuntu: GenerateK3sUninstallScript success (34.802683ms) +2024-12-17T19:52:41.268+0800 [A] ubuntu: ChmodScript(k3s) success (14.640733ms) +2024-12-17T19:52:41.268+0800 [Module] K3sInitClusterModule +2024-12-17T19:52:41.334+0800 [A] ubuntu: GenerateK3sService success (66.556896ms) +2024-12-17T19:52:41.379+0800 [A] ubuntu: GenerateK3sServiceEnv success (44.492752ms) +2024-12-17T19:52:41.414+0800 [A] ubuntu: GenerateK3sRegistryConfig success (34.814475ms) +2024-12-17T19:52:46.511+0800 [A] ubuntu: EnableK3sService success (5.097800474s) +2024-12-17T19:52:46.572+0800 [A] ubuntu: CopyKubeConfig success (60.33887ms) +... +``` +::: +### Integrate KubeSphere + +KubeSphere is installed on top of Kubernetes to enhance system management and observability. It provides features such as: + +- System monitoring and alerting. +- Resource and workspace management. +- Namespaces and custom resource definitions (CRDs). + +### Configure account +The Olares ID is created in the LarePass app. During this step, the installation script prompts you to enter the following info, so you can use LarePass to activate Olares later: +- **Olares domain name**: Olares provides default names `olares.com` and `olares.cn`. This can be customized if the custom domain has been added to Olares Space. +- **Olares ID**: Enter the username part of your Olares ID. + +This creates a system account for logging in to Olares and completes several background access and permission configurations. + +:::details Example script output +```bash +Enter the domain name ( olares.com by default ): +2024-12-17T20:58:15.690+0800 using Domain Name: olares.com + +Enter the Olares ID (which you registered in the LarePass app): marvin113 +2024-12-17T20:58:52.584+0800 using Olares Local Name: marvin113 +2024-12-17T20:58:52.584+0800 using Olares ID: marvin113@olares.com +2024-12-17T20:58:52.584+0800 using password: 2uO5PZ2X +``` +::: +### Deploy built-in applications +The final deployment step installs core services and user applications using Helm charts: +- **Core system services** (in the `os-system` namespace): Includes backups (Velero), storage (OpenEBS), Redis, Nats, MinIO, etc. +- **User applications** (in namespaces like `user-space-xxx`): Includes Files, Desktop, Settings, etc. + +During installation, the log will display messages such as `[helm] app installed success` and `xxx created`, indicating that the respective Helm charts or Kubernetes resources have been installed successfully. + +:::details Example script output +```bash +2024-12-17T19:53:18.382+0800 [A] ubuntu: InitKsNamespace success (2.678362348s) +2024-12-17T19:53:18.382+0800 [Module] DeploySnapshotController +customresourcedefinition.apiextensions.k8s.io/volumesnapshotclasses.snapshot.storage.k8s.io created +customresourcedefinition.apiextensions.k8s.io/volumesnapshotcontents.snapshot.storage.k8s.io created +customresourcedefinition.apiextensions.k8s.io/volumesnapshots.snapshot.storage.k8s.io created +2024-12-17T19:53:18.924+0800 [helm] app installed success {"NAME": "snapshot-controller", "LAST DEPLOYED": "Tue Dec 17 19:53:18 2024", "NAMESPACE": "kube-system", "STATUS": "deployed", "REVISION": 1} +2024-12-17T19:53:18.924+0800 [A] ubuntu: CreateSnapshotController success (541.656132ms) +2024-12-17T19:53:18.924+0800 [Module] DeployRedis +secret/redis-secret created +2024-12-17T19:53:19.057+0800 [A] ubuntu: CreateRedisSecret success (133.123121ms) +2024-12-17T19:53:19.189+0800 [A] ubuntu: BackupRedisManifests success (132.045425ms) +2024-12-17T19:53:19.339+0800 [A] ubuntu: DeployRedisHA success (149.251633ms) +local (default) openebs.io/local Delete WaitForFirstConsumer false 31s +local (default) openebs.io/local Delete WaitForFirstConsumer false 31s +2024-12-17T19:53:19.971+0800 [helm] app installed success {"NAME": "redis", "LAST DEPLOYED": "Tue Dec 17 19:53:19 2024", "NAMESPACE": "kubesphere-system", "STATUS": "deployed", "REVISION": 1} +... +``` +::: + +### Complete the installation + +Once all components are deployed, the script outputs a summary with a URL for the activation wizard: + +```bash +2024-12-17T21:00:58.086+0800 [INFO] Installation wizard is complete +2024-12-17T21:00:58.086+0800 [INFO] All done + +------------------------------------------------ + +2024-12-17T21:00:58.086+0800 Olares is running at: +2024-12-17T21:00:58.086+0800 http://192.168.1.16:30180 + +2024-12-17T21:00:58.086+0800 Open your browser and visit the above address +2024-12-17T21:00:58.086+0800 with the following credentials: + +2024-12-17T21:00:58.086+0800 Username: marvin113 +2024-12-17T21:00:58.086+0800 Password: 2uO5PZ2X +``` + +To complete the installation, you need to: +1. Open your browser and enter the provided URL. +2. Log in to the activation wizard with initial password. +3. Follow the on-screen prompt to finish the activation. + +After activation, your Olares will be fully operational and ready to use. + +## Learn more + +- [Olares installation overview](installation-overview.md) +- [Olares environment variables](environment-variables.md) \ No newline at end of file diff --git a/docs/developer/install/installation-troubleshooting.md b/docs/developer/install/installation-troubleshooting.md new file mode 100644 index 000000000..ae68503af --- /dev/null +++ b/docs/developer/install/installation-troubleshooting.md @@ -0,0 +1,9 @@ +--- +search:false +--- +:::info Troubleshooting installation issues +If any issues arise during installation, report them by [creating a GitHub issue](https://github.com/beclab/Olares/issues/new). Include the following details: +- The platform or environment being used (e.g., Ubuntu, Docker, WSL, etc.). +- The installation method (script or Docker image). +- Detailed error information (including logs, error messages, or screenshots). +::: \ No newline at end of file diff --git a/docs/developer/install/linux-via-docker-compose.md b/docs/developer/install/linux-via-docker-compose.md new file mode 100644 index 000000000..808115fca --- /dev/null +++ b/docs/developer/install/linux-via-docker-compose.md @@ -0,0 +1,128 @@ +--- +outline: [2, 3] +description: Learn how to deploy Olares on a Linux server using Docker Compose. This step-by-step guide covers system requirements, configuration, installation, activation, and container management. +--- +# Install Olares on Linux using Docker Compose +You can use Docker to install and run Olares in a containerized environment. This guide walks you through setting up Olares with Docker, preparing the installation environment, completing the activation process, and managing the container lifecycle. + +:::tip Recommendation for production use +For best performance and stability, we recommend [installing Olares on Linux via script](/manual/get-started/install-olares.md). +::: + +## System requirements + +Make sure your device meets the following requirements. + +- CPU: At least 4 cores +- RAM: At least 8GB of available memory +- Storage: At least 64GB of available space (SSD recommended) +- Supported systems: + - Ubuntu 20.04 LTS or later + - Debian 11 or later + +:::info Version compatibility +While these specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). +::: + +## Before you begin +Before you begin, ensure the following: +- [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) are installed and running on your system. +- You know the IP address of the current device. + :::tip Verify host IP + To verify your host IP, run the following command in the terminal: + ```bash + ip r + ``` + Look for the line starting with `default via`. It will show the default gateway and the network interface being used. + ::: +- You have [created an Olares ID via LarePass](/manual/get-started/create-olares-id.md). + +## Create a new directory +Create a directory to store the Olares configuration files. For example, you could make a new directory called `olares-config` with the following command: + +```bash +mkdir ~/olares-config +cd ~/olares-config +``` +## Prepare `docker-compose.yaml` +1. Create a `docker-compose.yaml` file in the `olares-config` directory. +2. Add the appropriate content to the file based on whether GPU support is required: + :::code-group + <<< @/code-snippets/docker-compose.yaml + <<< @/code-snippets/docker-compose-GPU.yaml + ::: +3. Save the `docker-compose.yaml` file. + +## Set up environment variables and start container + +1. In the `olares-config` directory, use the following command to set the environment variables and start the Olares services: + + ```bash [With Docker Compose Plugin] + VERSION= HOST_IP= docker compose up -d + ``` + - `VERSION=`: Specifies the Olares version. Replace `` with the actual one. For example: `1.11.5`. + - `HOST_IP=`: Specifies the Linux machine's IP address. Replace `` with the actual one. + + After executing the command, you should see output similar to the following, showing the status and port mappings of all containers: + ```bash + [+] Running 20/20 + ✔ olaresd-proxy Pulled 67.8s + ✔ 688513194d7a Pull complete 6.8s + ✔ bfb59b82a9b6 Pull complete 6.9s + ✔ efa9d1d5d3a2 Pull complete 9.5s + ✔ a62778643d56 Pull complete 9.6s + ✔ 7c12895b777b Pull complete 9.6s + ✔ 3214acf345c0 Pull complete 13.6s + ✔ 5664b15f108b Pull complete 14.1s + ✔ 0bab15eea81d Pull complete 14.2s + ✔ 4aa0ea1413d3 Pull complete 15.0s + ✔ da7816fa955e Pull complete 15.1s + ✔ 9aee425378d2 Pull complete 15.1s + ✔ 701c983262e9 Pull complete 36.2s + ✔ 221438ca359c Pull complete 36.3s + ✔ f3d0ed3b32e0 Pull complete 36.4s + ✔ 70d5c1f325f6 Pull complete 43.2s + ✔ olares Pulled 5863.6s + ✔ 2d5815038f40 Pull complete 5759.0s + ✔ 13788179ee16 Pull complete 5831.6s + ✔ 5a9b10c3302f Pull complete 5831.7s + ``` + +2. Verify if the container is running successfully: + ```bash + docker ps + ``` + You should see an output like this: + ```bash + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 28e86c473750 beclab/olaresd:proxy-v0.1.0 "/mdns-agent" About a minute ago Up About a minute olares-olaresd-proxy-1 + 5fd68a8709ad beclab/olares:1.11.5 "/usr/local/bin/entr…" 2 minutes ago Up About a minute 0.0.0.0:80->80/tcp... olares-olares-1 + ``` + + + +## Manage the Olares container +Ensure that you are in the directory containing the `docker-compose.yaml` file before proceeding with any commands. +### Stop the container +To stop the running container: +```bash +docker compose stop +``` + +### Restart the container +To restart the container after it has been stopped: +```bash +docker compose start +``` +It may take 6 to 7 minutes for all services to fully initialize after restarting. + +### Uninstall the container +To uninstall the container: +```bash +docker compose down +``` + + + + + diff --git a/docs/developer/install/log-in-to-olares.md b/docs/developer/install/log-in-to-olares.md new file mode 100644 index 000000000..9b0297592 --- /dev/null +++ b/docs/developer/install/log-in-to-olares.md @@ -0,0 +1,17 @@ +--- +search: false +--- +## Log in to Olares + +1. Enter the Olares desktop address in your browser, and press any key to continue. +2. On the login page, enter your Olares login password. + + ![Log in](/images/manual/get-started/log-in.png#bordered) +3. You will be prompted to complete the two-factor verification. You can confirm login on LarePass, or manually enter the 6-digit verification code. + ::: info + The verification code is time-sensitive. Ensure you enter it before it expires. If it does, you will need to generate a new code. + ::: + + ![Confirm login](/images/manual/get-started/confirm-login.png#bordered) + +Once you've logged in, you'll be directed to the Olares desktop.🎉 \ No newline at end of file diff --git a/docs/developer/install/lxc.md b/docs/developer/install/lxc.md new file mode 100644 index 000000000..295da936d --- /dev/null +++ b/docs/developer/install/lxc.md @@ -0,0 +1,153 @@ +--- +description: Instructions for installing Olares on Linux Containers (LXC) including container setup, system requirements, and activation steps. +--- +# Install Olares on LXC +LXC (Linux Containers) is a lightweight virtualization method that runs applications in isolated containers. When used on PVE, it enables an efficient way to deploy Olares without the overhead of a full virtual machine. + +:::warning Not recommended for production use +Currently, Olares on LXC has certain limitations. We recommend using it only for development or testing purposes. +::: + + + +## System requirements +Make sure your device meets the following requirements. + +- CPU: At least 4 cores +- RAM: At least 8GB of available memory +- Storage: At least 64GB of available space (SSD recommended) +- Supported systems: + - PVE 8.2.2 + - Linux container: Debian 12 (for existing LXC containers on PVE) + +:::info Version compatibility +While the specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). +::: + +## Prerequisites + +- Working directories for storing images and packages on the PVE host. You can set it using the following command: + + ``` bash + mkdir -p /root/.olares/images /root/.olares/pkg + ``` +- The container template (CT) for `debian-12-standard_12.7-1_amd64.tar.zst`. Download it from the [PVE image repository](http://download.proxmox.com/images/system/). + +## Configure the LXC environment + +::: tip Install on existing LXC +To install Olares on an existing LXC container, skip to step 2 directly. Make sure you use the corresponding container ID. +::: + +1. Create the LXC container using the following script: + + ::: tip Unique container ID + To create a container, you need to assign it a unique container ID. In this guide, we use `16553`, but you can replace it with any available numeric ID. Make sure to update all commands and configurations accordingly. + ::: + + ``` bash{2} + export ROOTPASS=123456 + pct create 16553 /var/lib/vz/template/cache/debian-12-standard_12.7-1_amd64.tar.zst \ + --hostname olares \ + --ostype ubuntu \ + --cores 4 \ + --memory 10240 \ + --swap 0 \ + --net0 name=eth0,bridge=vmbr0,firewall=1,ip=dhcp,ip6=dhcp,type=veth \ + --rootfs local-lvm:80 \ + --unprivileged 0 \ + --ignore-unpack-errors \ + --mp0 "/root/.olares/images,mp=/root/.olares/images" \ + --mp1 "/root/.olares/pkg,mp=/root/.olares/pkg" \ + --password="$ROOTPASS" + ``` + +2. Modify the LXC configuration. + + a. Open the configuration file using the following command: + + ``` bash + nano /etc/pve/lxc/16553.conf + ``` + + b. Copy and paste the following configurations into the file: + + ``` bash + arch: amd64 + cores: 4 + hostname: olares + memory: 10240 + net0: name=eth0,bridge=vmbr0,firewall=1,hwaddr=BC:24:11:13:05:7C,ip=dhcp,ip6=dhcp,type=veth + ostype: debian + rootfs: local-lvm:vm-16553-disk-0,size=80G + + # Storage config + mp0: /root/.olares/images,mp=/root/.olares/images + mp1: /root/.olares/pkg,mp=/root/.olares/pkg + + # Permision config + lxc.apparmor.profile: unconfined + lxc.cgroup.devices.allow: a + lxc.cap.drop: + lxc.mount.auto: "proc sys cgroup:mixed" + ``` + + c. Save and close the file. + +3. Enable IP Virtual Server (IPVS) modules on the PVE host: + + ``` bash + sudo modprobe ip_vs + sudo modprobe ip_vs_rr + sudo modprobe ip_vs_wrr + sudo modprobe ip_vs_sh + sudo modprobe overlay + ``` + +4. Start the LXC container, make initial configurations, and exit: + + ```bash + # Start the container + pct start 16553 + + # Enter the container + pct enter 16553 + + # Create missing directories + mkdir -p /lib/modules + + # Update PATH environment variable + echo 'export PATH="/usr/local/bin:$PATH"' >> /root/.bashrc + source ~/.bashrc + + # exit LXC + exit + ``` + +5. Copy PVE dependencies to the LXC container: + + ``` bash + # Copy kernel config from PVE host to LXC container + pct push 16553 /boot/config-$(uname -r) /boot/config-$(uname -r) + + # Package and copy kernel modules directory + tar cvf /lib/modules/6.8.4-2-pve.tar.gz /lib/modules/6.8.4-2-pve + pct push 16553 /lib/modules/6.8.4-2-pve.tar.gz /lib/modules/6.8.4-2-pve.tar.gz + + # Extract the archive inside the container + pct enter 16553 + cd /lib/modules + tar xvf /lib/modules/6.8.4-2-pve.tar.gz -C / + ``` + +## Install on LXC + +Run the following installation command inside the LXC container: + + + + + + + + \ No newline at end of file diff --git a/docs/developer/install/mac-via-docker-image.md b/docs/developer/install/mac-via-docker-image.md new file mode 100644 index 000000000..eb13d9648 --- /dev/null +++ b/docs/developer/install/mac-via-docker-image.md @@ -0,0 +1,100 @@ +--- +outline: [2, 3] +description: Learn how to run Olares as a containerized application on Mac with Docker, covering image setup and container configuration. +--- +# Install Olares on Mac with Docker image +You can use Docker to install and run Olares in a containerized environment. This guide walks you through setting up Olares with Docker, preparing the installation environment, completing the activation process, and managing the container lifecycle. + +:::warning Not for production use +Currently, Olares on Mac has certain limitations including: +- Lack of distributed storage support. +- Inability to add local nodes. + +We recommend using it only for development or testing purposes. +::: + + + +## System requirements +Make sure your device meets the following requirements. + +- Architecture: AMD64 or ARM64 +- CPU: At least 4 cores +- RAM: At least 8GB of available memory +- Storage: At least 64GB of available space (SSD recommended) + +## Before you begin +Before you begin, ensure the following: +- [Docker](https://www.docker.com/) is installed and running on your system. +- You know the IP address of the current device. + ::: tip View IP Address + To view the IP address on a Mac, there are two methods: + - Using the graphical interface: Open **System Settings** (or **System Preferences**) > **Network**, and check the details under the currently active network connection. + - Using the command line: Open a terminal window and enter `ipconfig getifaddr en0` for Wi-Fi, or `ipconfig getifaddr en1` for wired network. + ::: +- You have [created an Olares ID via LarePass](/manual/get-started/create-olares-id.md). + +## Run `olaresd-proxy` +::: tip Check Mac chip +If you are unsure which chip your Mac is using, go to the Apple menu and select **About This Mac** to verify. +::: + + + + + + +## Pull the Olares image + +To pull the image of Olares, execute the following command. + +Replace `` with your device's IP address and `` with the desired version of Olares: +```bash{2,9} +docker run -d --privileged -v oic-data:/var \ + -e HOST_IP= \ + -p 80:80 \ + -p 443:443 \ + -p 30180:30180 \ + -p 18088:18088 \ + -p 41641:41641/udp \ + --name oic \ + beclab/olares: +``` +where: + - `-d`: Starts the container in detached mode to allow it to run in the background. + - `--privileged`: Grants the container elevated privileges. + - `-v oic-data:/var`: Binds a Docker volume (`oic-data`) to the `/var` directory inside the container to persist data. + - `-e HOST_IP=`: Specifies the host device's IP address as an environment variable. + - `-p 80:80`: Maps port `80` on the host to port `80` in the container. + - `-p 443:443`: Maps port `443` on the host to port `443` in the container. + - `-p 30180:30180`: Maps port `30180` on the host to port `30180` in the container. + - `-p 18088:18088`: Maps port `18088` on the host to port `18088` in the container. + - `-p 41641:41641/udp`: Maps UDP port `41641` on the host to UDP port `41641` in the container. + - `--name oic`: Names the container `oic` (Olares in container) for easier reference. + - `beclab/olares:`: Specifies the Olares Docker image and version. For example: `beclab/olares:1.11.5`. + +When the container is running, you will see a container ID output. +::: +:::warning Do not add the `--rm` flag +The `--rm` flag automatically deletes the container after it stops. If this happens, you will not be able to restart the container and will need to reinstall Olares to run it again. Omitting this flag preserves the container after stoppage, enabling you to resume it with the`docker start` command. +::: + + + + + + diff --git a/docs/developer/install/mac.md b/docs/developer/install/mac.md new file mode 100644 index 000000000..61f51529c --- /dev/null +++ b/docs/developer/install/mac.md @@ -0,0 +1,49 @@ +--- +description: Step-by-step instructions for installing Olares on macOS systems including prerequisites, installation commands, and activation process. +--- +# Install Olares on Mac via the script +This guide explains how to install Olares on macOS using the provided installation script. + +:::warning Not for production use +Olares on Mac has certain limitations including: +- Lack of distributed storage support. +- Inability to add local nodes. + +We recommend using it only for development or testing purposes. +::: + + + +## System compatibility +Make sure your Mac meets the following requirements. +- Architecture: X86-64 or ARM64 +- RAM: 8 GB or above (available memory) +- Storage: 90 GB or above (available disk space) +- MacOS: Monterey (12) or later + +## Before you begin +Ensure you have the following installed: +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- [MiniKube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fmacos%2Farm64%2Fstable%2Fhomebrew) + ::: tip + It's recommended to install via `homebrew`. + ::: + +## Set up system environment +1. In Docker Desktop, navigate to **Settings** > **Resources**, and configure as below: + - **CPU limit**: Set to at least 4 CPUs + - **Memory limit**: Set to at least 9 GB + - **Virtual disk limit**: Set to at least 80 GB + + ![Update resource settings (example)](/images/manual/get-started/docker-resources-settings.png) +2. Click **Apply & restart** to implement the changes. +## Install Olares +In terminal, run the following command: + + + + + + + + \ No newline at end of file diff --git a/docs/developer/install/manage-olares-container.md b/docs/developer/install/manage-olares-container.md new file mode 100644 index 000000000..061e3b1af --- /dev/null +++ b/docs/developer/install/manage-olares-container.md @@ -0,0 +1,24 @@ +--- +search: false +--- +## Manage the Olares container + +### Stop the container +To stop the running container: +```bash +docker stop oic +``` + +### Restart the container +To restart the container after it has been stopped: +```bash +docker start oic +``` + +### Uninstall the container +To completely remove the container and its associated data: +```bash +docker stop oic +docker rm oic +docker volume rm oic-data +``` \ No newline at end of file diff --git a/docs/developer/install/olares-home.md b/docs/developer/install/olares-home.md new file mode 100644 index 000000000..5f32dc728 --- /dev/null +++ b/docs/developer/install/olares-home.md @@ -0,0 +1,66 @@ +--- +description: Internal structure of Olares Home directory organizing images, logs, dependencies and version management. Details about the default installation directory architecture. +--- +# Olares Home + +"Olares Home" is the default installation directory for Olares. It stores images, logs, dependency components, and version management data. In this document, you will learn the structure of Olares Home and gain a clearer understanding of the Olares installation process. + +## Path configuration + +By default, Olares Home is located at `~/.olares`. You can customize its location using the `--base-dir` option with a specific `olares-cli` command, for example: + +```bash +# Specifies the base directory where all downloaded components will be saved +olares-cli download component --base-dir /custom/path +``` + +## Directory structure + +A typical Olares Home directory might look like this: + +``` +./olares +├── images # Stores downloaded image files +│ ├── {image-file}.tar.gz +│ └── {image-file}.tar.gz +├── logs # Stores all logs +├── pkg # Stores downloaded system dependency components +│ ├── cni # Container Network Interface (K8s network plugins) +│ ├── components # Olares foundation software dependencies (not directly related to K8s) +│ │ such as olaresd, JuiceFS, Redis, etc. +│ ├── containerd # Container Runtime Interface (CRI) runtime +│ ├── crictl # CRI command-line tool +│ ├── etcd # Persistent database for K8s +│ ├── helm # Command-line tool for K8s application management +│ ├── kube # Core K8s programs (e.g., kubeadm, kubelet, k3s) +│ └── runc # Open Container Initiative (OCI) runtime +└── versions # Stores different Olares versions + ├── v1.10.0-20241001 + │ ├── cli + │ ├── deploy + │ ├── files + │ ├── images + │ ├── logs # Stores logs specific to this version of Olares + │ │ ├── install.log + │ │ └── uninstall.log + │ └── wizard # Contains Helm charts for system and user applications + └── v1.10.0-20240930 + ├── cli + ├── deploy + ├── files + ├── images + ├── logs + │ ├── install.log + │ └── uninstall.log + └── wizard +``` + +The structure of Olares Home is designed to optimize file management, version control, and resource sharing. The advantages include: +- Each Olares version is stored under the `versions` directory. All files and logs related to a particular version are contained within its subdirectory. +- Only one Olares instance can run on a single machine at a time, preventing version conflicts. +- The `images` and `pkg` directories are shared across all Olares versions. This design reduces redundancy, minimizes duplicate downloads, and saves disk space. + +## Learn more +- [Olares CLI](../install/cli/olares-cli.md) +- [Olares installation breakdown](installation-process.md) +- [Olares environment variables](environment-variables.md) diff --git a/docs/developer/install/pve.md b/docs/developer/install/pve.md new file mode 100644 index 000000000..ed6491390 --- /dev/null +++ b/docs/developer/install/pve.md @@ -0,0 +1,35 @@ +--- +description: Guide to installing Olares on Proxmox VE (PVE) with system requirements, installation commands, and step-by-step activation instructions. +--- +# Install Olares on PVE +Proxmox Virtual Environment (PVE) is an open-source virtualization platform based on Debian Linux. This guide explains how to install Olares in a PVE environment. + +:::warning Not recommended for production use +Currently, Olares on PVE has certain limitations. We recommend using it only for development or testing purposes. +::: + + + +## System requirements +Make sure your device meets the following requirements. + +- CPU: At least 4 cores +- RAM: At least 8GB of available memory +- Storage: At least 64GB of available space (SSD recommended) +- Supported Systems: PVE 8.2.2 + +:::info Version compatibility +While the specific version is confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). +::: + +## Install on PVE + +In PVE CLI, run the following command: + + + + + + + + \ No newline at end of file diff --git a/docs/developer/install/raspberry-pi.md b/docs/developer/install/raspberry-pi.md new file mode 100644 index 000000000..52966fac5 --- /dev/null +++ b/docs/developer/install/raspberry-pi.md @@ -0,0 +1,41 @@ +--- +description: Complete guide to installing Olares on Raspberry Pi including hardware requirements, installation process, and system activation steps. +--- +# Install Olares on Raspberry Pi +This guide explains how to install Olares on a Raspberry Pi. + +:::warning Not recommended for production use +Currently, Olares on Raspberry Pi has certain limitations. We recommend using it only for development or testing purposes. +::: + + +## System requirements +Make sure your Raspbian device meets the following requirements. +- Hardware: Raspberry Pi 4B or Raspberry Pi 5 with 8GB memory +- Operating system: Raspbian 12 +- Storage: 64GB (SSD recommended) + +## Set up system environment +1. Configure the Raspbian environment to enable necessary features: + + ```bash + echo "$(head -1 /boot/firmware/cmdline.txt) cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1" | sudo tee /boot/firmware/cmdline.txt + + echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt + ``` + +2. Reboot your Raspbian device to apply the change. + + ```bash + sudo reboot + ``` +## Install Olares +Run the following command: + + + + + + + + \ No newline at end of file diff --git a/docs/developer/install/reusables.md b/docs/developer/install/reusables.md new file mode 100644 index 000000000..0df2238fa --- /dev/null +++ b/docs/developer/install/reusables.md @@ -0,0 +1,51 @@ +--- +search: false +--- + +```bash +curl -fsSL https://olares.sh | bash - +``` + +:::tip Root user password +During the installation, you may be prompted to enter your root password. +::: + +:::info Errors during installation? +If an error occurs during installation, use the following command to uninstall first: + +```bash +olares-cli uninstall --all + +``` + +After uninstalling, retry the installation by running the original installation command. +::: + +## Prepare Wizard URL + +At the end of the installation process, you will be prompted to enter your domain name and Olares ID. + +![Enter domain name and Olares ID](/images/manual/get-started/enter-olares-id.png) + +For example, if your full Olares ID is `alice123@olares.com`: + +- **Domain name**: Press `Enter` to use the default domain name or type `olares.com`. +- **Olares ID**: Enter the prefix of your Olares ID. In this example, enter `alice123`. + +Upon completion of the installation, the initial system information, including the Wizard URL and the initial login password, will appear on the screen. You will need them later in the activation stage. + +![Wizard URL](/images/manual/get-started/wizard-url-and-login-password.png) + +## Next step: Protect your Olares ID + +You're almost ready to start using Olares! Before diving in, it's crucial to ensure your Olares ID is securely backed up. Without this step, you won't be able to recover Olares ID if needed. + +- [Back up your mnemonic phrase](/manual/larepass/back-up-mnemonics.md) + +:::info Having trouble with installation? +If you encounter issues during the installation process, feel free to [submit a GitHub Issue](https://github.com/beclab/Olares/issues/new). Please include the following information when submitting: + +- The platform or environment you're using (e.g., Ubuntu, Docker, WSL, etc.). +- The installation method (script installation or Docker image). +- Detailed error information (including logs, error messages, or screenshots). + ::: diff --git a/docs/developer/install/versioning.md b/docs/developer/install/versioning.md new file mode 100644 index 000000000..539d5b0fa --- /dev/null +++ b/docs/developer/install/versioning.md @@ -0,0 +1,73 @@ +--- +outline: [2, 3] +description: Version management system in Olares covering release types, branch strategies and upgrade specifications. Details about semantic versioning implementation and compatibility. +--- +# Olares versioning + +The Olares versioning and release process is designed to provide clear version definitions and stable upgrade paths. This document outlines Olares' versioning rules, release types, branch management practices, and upgrade guidelines. + +## Versioning rules + +Olares primarily follows the [Semantic versioning specification](https://semver.org/), which defines versions in format `Major.Minor.Patch[-PreReleaseVersion]`. For example, `1.11.0-rc.0` represents a release candidate for version `1.11.0`. + +Versions are ordered as follows: + `1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` < `1.0.0` + + +## Release types + +Olares offers three types of releases: **Stable**, **Release Candidate (RC)**, and **Daily build**. + +### Stable releases + +Stable releases are thoroughly tested versions suitable for production environments. The official one-line installation command always defaults to the latest stable version. +- **Release cadence**: Monthly +- **Examples**: `v1.10.5`, `v1.11.0`, `v1.11.1`, `v1.12.0` + +### Release Candidate (RC) releases + +RC releases are pre-release versions for testing before a stable release. RC releases may go through several iterations before being promoted to stable. +- **Release cadence**: Based on testing status +- **Examples**: `v1.11.0.rc.0`, `v1.11.0.rc.1` + +### Daily build releases + +Daily build releases, or daily builds are automatically generated from the `main` branch every day at 2:00 AM (UTC+8), with the build date embedded in the version name. These versions reflect the latest code changes and are intended for development and testing purposes. Daily builds are often unstable and not suitable for production use. +- **Release cadence**: Daily +- **Examples**: `v1.12.0-20241201` + +## Release branch management + +During the `1.x` phase, Olares follows a structured monthly release cadence: + +1. At the end of each month, a release branch (e.g., `release-1.11`) is created from the `main` branch. + +2. An initial RC version (e.g., `v1.11.0.rc.0`) is released from the new release branch. Additional RC versions may follow as testing progresses. + +3. The `main` branch transitions to the next version (e.g., from `v1.11` to `v1.12`). + +4. Issues identified in the stable version are addressed through patch releases (e.g., `v1.11.1`), based on the corresponding release branch. + +Developers can submit pull requests (PRs) to both the `main` branch and the relevant release branch as needed. + +## Upgrade policies and compatibility + +Olares is in a rapid development phase with frequent feature additions and changes. To ensure stability and avoid unexpected issues, Olares follows a controlled upgrade policy: + +- **Upgrades within the same minor version**: + + Upgrading within the same minor version (e.g., `1.4.0` to `1.4.2`) is fully supported. These updates typically include bug fixes or small improvements that do not affect compatibility. + +- **Upgrades across minor versions**: + + Upgrading from one minor version to another (e.g., `1.4.x` to `1.5.x`) involves more significant changes, such as new features or architectural updates. Because these changes may not be backward-compatible, automatic upgrades are **not supported**. Instead, users must manually uninstall the existing version before installing the newer version. + +The type of release you are using also determines what upgrades are possible: + +- **Stable**: You can only upgrade to newer stable releases, ensuring maximum reliability and stability. +- **RC**: You can upgrade to newer RC versions or stable releases as they become available. +- **Daily build**: You can upgrade to newer daily build, RC, or stable releases. + +::: tip Future upgrade policy +In the next major release, Olares plans to fully support seamless automatic upgrades for all versions within the same major version. +::: diff --git a/docs/developer/install/windows-via-docker-image.md b/docs/developer/install/windows-via-docker-image.md new file mode 100644 index 000000000..3ea3d241d --- /dev/null +++ b/docs/developer/install/windows-via-docker-image.md @@ -0,0 +1,149 @@ +--- +outline: [2, 3] +description: Learn how to run Olares on Windows using WSL 2 and Docker, including system preparation, configuration, and container management. +--- +# Install Olares on Windows (WSL 2) with Docker image +You can use Docker to install and run Olares in a containerized environment. This guide walks you through setting up Olares with Docker and WSL 2, preparing the installation environment, completing the activation process, and managing the container lifecycle. + +:::warning Not recommended for production use +Currently, Olares on Windows has certain limitations including: +- Lack of distributed storage support +- Inability to add local nodes. + +We recommend using it only for development or testing purposes. +::: + + +## System requirements +Make sure your Windows meets the following requirements. +- CPU: At least 4 cores +- RAM: At least 16GB of available memory +- Storage: At least 64GB of available space (SSD recommended) +- Supported systems: + - Windows 10 or 11 + - Linux (on WSL 2): Ubuntu 20.04 LTS or later; Debian 11 or later + +## Before you begin +Before you begin, ensure the following: +- [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) is installed and running on your system. + :::info WSL 2 and Hyper-V + If Docker Desktop is configured to use **Hyper-V**, GPU support for Olares cannot be enabled. Ensure Docker Desktop is set to run in the **WSL 2** mode. + ::: +- You know the IP address of the current device. + ::: tip View IP Address + In PowerShell or Command Prompt, use the following command to confirm your IP address: + ```bash + ipconfig | findstr /i "IPv4.*192" + ``` + ::: +- You have [created an Olares ID via LarePass](/manual/get-started/create-olares-id.md). + +## Configure WSL 2 +1. Open PowerShell and run the following command to confirm the kernel version of WSL installed on your system: + ```powershell + wsl --version + ``` + Example output: + ```PowerShell{2} + WSL version: 2.4.8.0 + Kernel version: 5.15.167.4-1 + WSLg version: 1.0.65 + MSRDC version: 1.611.1-81528511 + DXCore version: 10.0.26100.1-240331-1435.ge-release + Windows version: 10.0.26100.3475 + ``` +2. Use the link provided to download the appropriate kernel file matching your version: `https://dc3p1870nn3cj.cloudfront.net/bzImage-`. + For example, For kernel version `5.15.167.4`, download the file from `https://dc3p1870nn3cj.cloudfront.net/bzImage-5.15.167.4`. + + Supported kernel versions (above `5.15.146.1`) are: + - `linux-msft-wsl-5.15.146.1` + - `linux-msft-wsl-5.15.150.1` + - `linux-msft-wsl-5.15.153.1` + - `linux-msft-wsl-5.15.167.4` + - `linux-msft-wsl-6.6.75.1` + - `linux-msft-wsl-6.6.36.6` + - `linux-msft-wsl-6.6.36.3` +3. Set the default version of WSL to version 2: + ```bash + wsl --set-default-version 2 + ``` +4. In the directory `C:\Users\\`, create a file named `.wslconfig` with the following content: + ```txt + [wsl2] + kernel=c:\\path\\to\\your\\kernel\\bzImage- # Note: Use double backslashes (\\) as path separators + memory=8GB # Recommended: 16GB + swap=0GB + ``` + :::info + If you installed Docker Desktop before modifying the `.wslconfig` file, it is recommended to remove the `docker-desktop` distribution installed under WSL: + ```bash + wsl --unregister docker-desktop + wsl --unregister docker-desktop-data # If this version exists + ``` + ::: +5. Restart your computer to apply the changes. + +## Prepare Docker +If you have installed Docker Desktop before modifying `.wslconfig`, remove docker desktop then restart Windows. + +## Run `olaresd-proxy` +1. Download `olaresd-proxy`from the following link: `https://dc3p1870nn3cj.cloudfront.net/olaresd-proxy-v0.1.0-windows-amd64.tar.gz`. +2. Extract the file and start the `olaresd-proxy` executable. + :::info Keep `olaresd-proxy` running + Ensure that `olaresd-proxy` runs in the background during the installation and activation of Olares. + ::: + +## Run Olares using the Docker CLI +:::warning CUDA version requirements +CUDA version 12.4 or above is required for GPU support. Older versions are incompatible. +::: +Run the following command to pull the Olares image. +Replace `` with your device's IP address and `` with the desired version of Olares: +::: code-group +```bash{2,9} [Without GPU support] +docker run -d --privileged -v oic-data:/var \ + -e HOST_IP= \ + -p 80:80 \ + -p 443:443 \ + -p 30180:30180 \ + -p 18088:18088 \ + -p 41641:41641/udp \ + --name oic \ + beclab/olares: +``` +```bash{1,2,9} [With GPU support] +docker run --gpus all -d --privileged -v oic-data:/var \ + -e HOST_IP= \ + -p 80:80 \ + -p 443:443 \ + -p 30180:30180 \ + -p 18088:18088 \ + -p 41641:41641/udp \ + --name oic \ + beclab/olares: +``` +::: +where: + - `-d`: Starts the container in detached mode to allow it to run in the background. + - `--privileged`: Grants the container elevated privileges. + - `-v oic-data:/var`: Binds a Docker volume (`oic-data`) to the `/var` directory inside the container to persist data. + - `-e HOST_IP=`: Specifies the host device's IP address as an environment variable. + - `-p 80:80`: Maps port `80` on the host to port `80` in the container. + - `-p 443:443`: Maps port `443` on the host to port `443` in the container. + - `-p 30180:30180`: Maps port `30180` on the host to port `30180` in the container. + - `-p 18088:18088`: Maps port `18088` on the host to port `18088` in the container. + - `-p 41641:41641/udp`: Maps UDP port `41641` on the host to UDP port `41641` in the container. + - `--name oic`: Names the container `oic` (Olares in container) for easier reference. + - `beclab/olares:`: Specifies the Olares Docker image and version. For example: `beclab/olares:1.11.5`. + +When the container is running, you will see a container ID output. + +:::warning Do not add the `--rm` flag +The `--rm` flag automatically deletes the container after it stops. If this happens, you will not be able to restart the container and will need to reinstall Olares to run it again. Omitting this flag preserves the container after stoppage, enabling you to resume it with the`docker start` command. +::: + + + + + + diff --git a/docs/developer/install/windows.md b/docs/developer/install/windows.md new file mode 100644 index 000000000..9517edc34 --- /dev/null +++ b/docs/developer/install/windows.md @@ -0,0 +1,234 @@ +--- +outline: [2, 3] +description: Guide to installing Olares on Windows using WSL (Windows Subsystem for Linux) including setup requirements and activation steps. +--- +# Install Olares on Windows via the script +This guide explains how to install Olares on Windows (WSL 2) using the provided installation script. + +:::warning Not recommended for production use +Currently, Olares on Windows has certain limitations including: +- Lack of distributed storage support +- Inability to add local nodes. + +We recommend using it only for development or testing purposes. +::: + + +## System compatibility +Make sure your Windows meets the following requirements. +- CPU: At least 4 cores +- RAM: At least 16GB of available memory +- Storage: At least 64GB of available space (SSD recommended) +- Supported systems: + - Windows 10 or 11 + - Linux (on WSL 2): Ubuntu 20.04 LTS or later; Debian 11 or later +## Set up system environment +1. Enable the required Windows features for virtualization. + + a. Open **Control Panel**, then go to **Programs** > **Programs and Features** > **Turn Windows features on or off**. + + b. In the **Windows Features** window, check: + - **Hyper-V** (not required for Windows 10 Home and Windows 11 Home) + - **Windows Subsystem for Linux** + - **Virtual Machine Platform** + + c. Click **OK** and restart your computer when prompted. + +2. Set the execution policy for the current user. + + a. Open PowerShell as administrator, then run the following command: + ```powershell + Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser + ``` + b. When prompted to check whether to change the execution policy, type `A` and press **Enter** to confirm. + + ```powershell{5} + Execution Policy Change + The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose + you to the security risks described in the about_Execution_Policies help topic at + https:/go.microsoft.com/fwlink/?LinkID-135170. Do you want to change the execution policy? + [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): + ``` + +## Install Olares +1. Click https://windows.olares.sh to download the installation script `publicInstall.latest.ps1`. + +2. Execute the script. + + a. Open PowerShell as administrator, then navigate to the folder where the script is located. For example, if the script is in the `Downloads` folder, run the following command: + ```powershell + cd C:\Users\\Downloads + ``` + + b. Once in the correct folder, run the following command: + ```powershell + .\publicInstall.latest.ps1 + ``` + + :::warning Administrator privileges required + Running PowerShell without administrator privileges will cause the installation to fail. See [How to make sure I am using PowerShell as administrator](#how-to-make-sure-i-am-using-powershell-as-administrator). + ::: + +3. When prompted with security warning, type `R` and press **Enter** to run the script once. The installation process for Olares will start. + + ```powershell{4} + Security warning + Run only scripts that you trust. While scripts from the internet can be useful, this script can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning message. Do you want to run + publicInstall.latest.ps1? + [D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"): + ``` + +4. When prompted to select the drive to store the WSL Ubuntu distro, type the drive letter of an available disk. Ensure the selected drive has at least **80 GB** of free space. + ```powershell{8} + Installing Olares will create a WSL Ubuntu Distro and occupy at least 80 GB of disk space. + Please select the drive where you want to install it. + + Available drives and free space: + C:\ Free Disk: 391.07 GB + D:\ Free Disk: 281.32 GB + + Please enter the drive letter (e.g., C): + ``` + +5. When prompted with the firewall rules setup, type `yes` to automatically configure them, or type `no` to skip this step.
+ If you choose to skip, either [disable Windows Firewall Defender](#how-to-disable-windows-defender-firewall), or [manually add TCP inbound rules](#how-to-manually-set-firewall-rules). + ```powershell{2} + Accessing Olares requires setting up firewall rules, specifically adding TCP inbound rules for ports 80, 443, and 30180. + Do you want to set up the firewall rules? (yes/no): + ``` +6. When promoted to confirm the IP address of Windows, type **Y** to confirm, or **R** to re-enter. + + ```powershell + The NAT gateway (the Windows host)'s IP is 192.168.50.136. Confirm [Y] or Re-enter [R]? + ``` + ::: tip Obtain the IPv4 address of Windows + You can get the IPv4 address in advance by running `ipconfig` in the Windows command line. + ::: + + + +:::info Errors during installation? +If an error occurs during installation, use the following command to uninstall first: +```powershell +wsl --unregister ubuntu +``` +After uninstalling, retry the installation by running the original installation command. +::: + + + + + + + + +## FAQ + +### How to make sure I am using PowerShell as administrator? +You can confirm that PowerShell is running as an administrator if you see "Administrator: Windows PowerShell" in the title bar of the PowerShell window. + +![Confirm run Powershell as administrator](/images/manual/get-started/confirm-run-powershell-as-admin.png#bordered){width=70%} + +If not, use one of the following methods: +- Search for "PowerShell" in the **Start** menu, right-click it, and select **Run as administrator**. +- Or press **Win** + **R**, type `powershell`, and press **Ctrl** + **Shift** + **Enter** to open PowerShell as an administrator. + +### How to configure the CPU and memory for WLS? +When installing Olares in WSL, the default memory allocation is `12GB`. But you can configure the memory before Olares installation, or adjust both memory and CPU settings after installation. + +**Adjust the memory setting before installation** + +For example, to allocate 16GB of memory: + +1. Add a user variable with the following: + - **Variable name**: `WSL_MEMORY` + - **Variable value**: `16` + + ![Add user variable](/images/manual/get-started/add-user-variable.png#bordered) + +2. Click **OK** to apply changes. + + :::tip + If you already have a PowerShell window open, changes to environment variables will not take effect in the current session. To ensure the updated environment variables are loaded, open a new PowerShell terminal as administrator, and then run the installation script. + ::: + +**Adjust memory and CPU settings after installation** + +After installation, a configuration file named `.wslconfig` will be created in the current user's home directory (`C:\Users\\`). This file allows you to adjust memory and CPU settings. The default configuration looks like this: + +```bash +[wsl2] +memory=12GB +swap=0GB +``` + +For example, to use 4 CPU cores: +1. Add the `processors` parameter to the file: + ```bash + [wsl2] + memory=12GB + processors=4 + swap=0GB + ``` +2. Save the `.wslconfig` file with your custom changes. +3. Close all running virtual machines by running the following command in PowerShell: + ```powershell + wsl --shutdown + ``` +4. Restart Olares by running: + ```powershell + wsl -d Ubuntu + ``` +It will take a few minutes for Olares services to restart. + +### How to reactivate Olares after the PC restarts? +Run the following command in PowerShell to restart the Olares service: +```powershell +wsl -d Ubuntu +``` + +### How to disable Windows Defender Firewall? +:::tip +You can turn on Windows Defender Firewall when the Olares installation completes. +::: +To completely disable the firewall: +1. Open **Control Panel** > **System and Security** > **Windows Defender Firewall**. +2. In the navigation pane, click **Turn Windows Defender Firewall on or off**. +3. Select **Turn off Windows Defender Firewall** for both private and public networks, then click **OK**. + + ![Turn off Windows Defender Firewall](/images/manual/get-started/disable-firewall.png#bordered) + +### How to manually set firewall rules? +If you choose not to configure firewall rules during installation, follow these steps to set them manually: +1. Open **Control Panel** > **System and Security** > **Windows Defender Firewall**. + + ![Navigate to Windows Defender Firewall](/images/manual/get-started/select-firewall.png#bordered) + +2. In the navigation pane, select **Advanced settings**. + + ![Select Advanced settings](/images/manual/get-started/select-advanced-settings.png#bordered) +3. In the navigation pane, right-click **Inbound Rules** and select **New Rule**. + + ![Add new rule](/images/manual/get-started/add-new-rule.png#bordered) +4. In the **New Inbound Rule Wizard**, select **Port** and click **Next**. + + ![Select Port](/images/manual/get-started/select-port.png#bordered) +5. In **Specific local ports**, enter `80`, `443`, `30180`, and click **Next**. + + ![Specify Port](/images/manual/get-started/specify-port.png#bordered) +6. Select **Allow the connection** and click **Next**. + + ![Allow the connection](/images/manual/get-started/allow-the-connection.png#bordered) + +7. Confirm the rules apply to **Domain**, **Private**, and **Public**, then click **Next**. + + ![Confirm rules](/images/manual/get-started/confirm-rules.png#bordered) +8. Provide a name for the rule and click **Finish**. + + ![Name the rule](/images/manual/get-started/name-the-rule.png#bordered) + +### How to uninstall Olares? +Run the following command in PowerShell: +```powershell +wsl --unregister ubuntu +``` \ No newline at end of file diff --git a/docs/extensions.json b/docs/extensions.json new file mode 100644 index 000000000..aee140d57 --- /dev/null +++ b/docs/extensions.json @@ -0,0 +1,7 @@ +{ + "recommendations": [ + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "vue.vscode-typescript-vue-plugin" + ] +} diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..d3963c0f7 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,59 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: "Olares" + text: "An open-source personal cloud OS" + tagline: "Let people own their data again" + actions: + - theme: brand + text: What is Olares? + link: /manual/docs-home + - theme: alt + text: Star us on GitHub + link: https://github.com/beclab/olares + +features: +- icon: 🚀 + title: Get started with Olares + details: Install Olares on your hardware and begin taking control of your data in minutes. + link: /manual/get-started/ + +- icon: ⚙️ + title: Master your system + details: Dive into Olares' system apps to configure, personalize, and access your personal cloud. + link: /manual/olares/ + +- icon: 📱 + title: Hands-on with LarePass + details: Securely access and manage your Olares from LarePass, the cross-platform client for Olares. + link: /manual/larepass/ + +- icon: 💡 + title: Explore Use Cases + details: Discover various ways you can leverage Olares in daily life with real-life tutorials and use cases. + link: /use-cases/ +--- + + diff --git a/docs/manual/best-practices/index.md b/docs/manual/best-practices/index.md new file mode 100644 index 000000000..5c8aafe36 --- /dev/null +++ b/docs/manual/best-practices/index.md @@ -0,0 +1,12 @@ +--- +description: In-depth guides and proven best practices to help you get the most out of Olares. +--- +# Beyond the basics: Olares best practices and advanced guides + +This section offers in-depth guides and proven best practices to help you get the most out of Olares. Whether you're optimizing performance, securing your environment, or customizing advanced features, these resources go beyond initial setup to support real-world scenarios and power-user workflows. + +- [Configure a custom domain for your Olares](set-custom-domain.md) +- [Install a multi-node Olares cluster](install-olares-multi-node.md) +- [Build your knowledge hub with Wise](organize-content.md) + + diff --git a/docs/manual/best-practices/install-olares-multi-node.md b/docs/manual/best-practices/install-olares-multi-node.md new file mode 100644 index 000000000..1ed2c1188 --- /dev/null +++ b/docs/manual/best-practices/install-olares-multi-node.md @@ -0,0 +1,158 @@ +--- +outline: [2, 3] +description: Technical guide for installing and configuring a multi-node Olares cluster. Learn how to set up master nodes with JuiceFS support, add worker nodes, and handle network changes in your cluster environment. +--- + +# Install a multi-node Olares cluster + +The default Olares installation sets up a single-node cluster. Starting from v1.11.3, Olares supports adding worker nodes. This tutorial explains how to configure a master node and add worker nodes to create a scalable, multi-node Olares cluster. + +:::warning Alpha feature +This feature is currently in the **Alpha** stage and is not recommended for production environments. It may contain performance issues and require additional manual configurations. If you encounter any issues, please report them to the [Olares GitHub repository](https://github.com/beclab/Olares/issues). +::: +:::info Linux-only support +This feature is currently only available for Linux systems. +::: + +## Objectives + +In this tutorial, you will learn how to: + +- Install Olares on the master node with support for JuiceFS. +- Add a worker node to the cluster. +- Handle potential network changes to ensure the cluster continues to function properly and efficiently. + +## Before you begin + +Before you begin, make sure the following requirements are met: + +- Prior experience with Kubernetes and system administration. +- Both master and worker nodes must be on the same local network. +- Master and worker nodes must have unique hostnames to avoid conflicts. +- The worker node must be able to connect to the master node via SSH. This means: + - For the root user or a user with `sudo` privileges: add the worker node's SSH public key to the master node's `authorized_keys` file. + - For non-root user: enable password-based SSH authentication on the master node. + +## Step 1: Set up the master node + +::: tip Uninstall existing Olares cluster +If you have already installed an Olares cluster using the default installation command, uninstall it using `olares-cli uninstall --all` before you set up your master node. +::: + +To set up the master node with the JuiceFS support, run the following command: + +```bash +export JUICEFS = 1 \ +&& curl -sSfL https://olares.sh | bash - +``` + +This command installs Olares with a built-in MinIO instance as the backend storage. The installation process is identical to a single-node one and will prompt you to enter the domain name, and provide username of your Olares ID. + +:::tip Custom storage +If you already have your own MinIO cluster or an S3 (or S3-compatible) bucket, you can configure Olares to use it instead of the built-in MinIO instance. +::: + +## Step 2: Add a worker node to the cluster + +1. On the worker node, download `joincluster.sh` from https://joincluster.com. +2. Run the `joincluster.sh` script with the necessary environment variables. These variables tell the worker node how to connect to the master node. At a minimum, you must set the MASTER_HOST variable, which specifies the IP address of the master node: + ```bash + export MASTER_HOST=192.168.1.15 + ./joincluster.sh + ``` + +Below is a list of the variables you might need to set: + +| **Variable** | **Description** | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `MASTER_HOST` | The IP address of the master node.
Required. | +| `MASTER_NODE_NAME` | The Kubernetes node name of the master node.
If not specified, the script will prompt you interactively to confirm the required parameter.
Optional. | +| `MASTER_SSH_USER` | The username to log in to the master node via SSH.
By default, this is root. | +| `MASTER_SSH_PASSWORD` | The password for the SSH user.
This is required if you're not using SSH keys. | +| `MASTER_SSH_PRIVATE_KEY_PATH` | The path to the private SSH key for authentication.
If not specified, the script will prompt you interactively to confirm the required parameter.
Defaults to `/root/.ssh/id_rsa`. | +| `MASTER_SSH_PORT` | The port number for the SSH service on the master node.
Defaults to `22`. | + +:::info + +- Non-root users must provide a password to execute commands with `sudo`. Therefore, using a non-root `MASTER_SSH_USER` without specifying `MASTER_SSH_PASSWORD` is not allowed. +- Environment variables set with `export` will remain active in your current terminal session. Be careful to clear (`unset`) any conflicting variables when switching between different setups. + `bash + unset MASTER_SSH_PRIVATE_KEY_PATH + ` + ::: + +## Examples + +Here are practical examples to help you understand how to run the `joincluster.sh` script under different scenarios. + +### Example 1: Default setup + +If the master node IP is `192.168.1.15`, the default user is `root`, the port is `22`, and the master node's `/root/.ssh/authorized_keys` already contains the public key `/root/.ssh/id_rsa.pub` from the current node, run: + +```bash +export MASTER_HOST=192.168.1.15 +./joincluster.sh +``` + +### Example 2: Custom SSH key path + +If the master node IP is `192.168.1.15`, with SSH port `22` and SSH user `root`, and the worker node uses a custom SSH key located at `/home/olares/.ssh/id_rsa`, run: + +```bash +export MASTER_HOST=192.168.1.15 \ + MASTER_SSH_PRIVATE_KEY_PATH=/home/olares/.ssh/id_rsa +./joincluster.sh +``` + +### Example 3: Non-root user with password + +If the master node is at `192.168.1.15`, with SSH port `22`, and the SSH user is `olares` (a sudo-privileged user) with the password `olares`, run: + +```bash +export MASTER_HOST=192.168.1.15 \ + MASTER_SSH_USER=olares \ + MASTER_SSH_PASSWORD=olares +./joincluster.sh +``` + +## Uninstall a worker node + +On the worker node, run the following: + +```bash +olares-cli olares uninstall +``` + +## Handle network changes + +Once your cluster is set up, changes in network configurations can disrupt the master-worker communication. + +### If the network of master node changes + +- **If the master node moves to a different LAN**: The Olares system daemon (olaresd) will detect this and trigger a `changeip` event with `olares-cli`. The master node will continue working, but worker nodes will lose communication with it and stop functioning. + +- **If the master node's IP changes within the same LAN**: The worker nodes will still lose communication because they cannot detect the new IP automatically. To resolve this, use the `olares-cli` command on the worker nodes to update the master node's IP address and restart the dependent services: + + ```bash + sudo olares-cli olares change-ip -b /home/olares/.olares --new-master-host 192.168.1.18 + ``` + + where: + + - `-b /home/olares/.olares`: Specifies the base directory for Olares (default: `$HOME/.olares`). + - `--new-master-host 192.168.1.18`: Specifies the new IP address of the master node. + +### If the network of worker node changes + +- **If a worker node moves to a different LAN**: The worker node will lose communication with the master node and stop functioning. + +- **If the worker node's IP changes within the same LAN**: olaresd will automatically report the new IP to the master node, and no manual intervention is required. + +## Learn more + +- [Olares system architecture](../system-architecture.md#distributed-file-system): Understand the distributed file system that underpins Olares, ensuring scalability, high availability, and seamless data management. +- [The system daemon: olaresd](../../developer/install/installation-overview.md#system-daemon-olaresd): Learn about the central system process that orchestrates and manages core Olares functions. +- [Data](../concepts/data.md#juicefs): Dive into how Olares leverages JuiceFS to provide a unified file system for efficient data storage and retrieval. +- [Olares CLI](../../developer/install/cli/olares-cli.md): Explore the command-line interface for managing Olares installation. +- [Olares environment variables](../../developer/install/environment-variables.md): Learn about the environment variables that enable advanced configurations of Olares. +- [Install Olares](../get-started/install-olares.md): Understand how to install and activate Olares. diff --git a/docs/manual/best-practices/organize-content.md b/docs/manual/best-practices/organize-content.md new file mode 100644 index 000000000..22218459d --- /dev/null +++ b/docs/manual/best-practices/organize-content.md @@ -0,0 +1,204 @@ +--- +outline: [2, 3] +description: Complete guide to building your knowledge hub with Wise in Olares. Learn how to collect web content, manage PDFs and e-books, subscribe to RSS feeds, and organize your digital content library effectively. +--- +# Build your knowledge hub with Wise + +Managing information across different sources and devices can be a challenge. You might find yourself using multiple tools to bookmark articles, track RSS feeds, or manage documents, only to end up with fragmented workflows. + +Wise, a built-in app in Olares, is designed to centralize and organize your knowledge. It collects information from the web and your devices, using local recommendation algorithms to help you discover meaningful content privately and free from algorithmic bias. + +This tutorial guides you on how to leverage Wise and LarePass to collect, organize, and access content across platforms. + +## Objectives + +By the end of this tutorial, you will learn how to: + +- Use LarePass Chrome browser extension or mobile client to collect content directly from the web while you browse. +- Organize your existing files, such as PDFs and EPUBs, by uploading them into Wise. +- Stay up-to-date with your favorite blogs, podcasts, or video playlists by subscribing to RSS feeds. +- Quickly locate and retrieve any piece of content from your curated information hub. + +## Before you begin + +Before you begin, make sure that: + +- Your Olares device is activated and actively running. +- Your Olares ID is [secured with mnemonic phrases](/manual/larepass/back-up-mnemonics.md). +- The LarePass app is installed on your phone. + +## Install the LarePass browser extension + +The LarePass browser extension is the core tool for content discovery and collection. + +::: tip Support for Chrome only +The LarePass extension is currently only available for Chrome. +::: + + + + + + +:::tip Quick access +After installation, pin the LarePass extension in Chrome extension menu for quick and easy access. +::: + +Once logged in, your LarePass browser extension and your Olares device are synced. This means that any content you collect via LarePass extension will automatically be added to your Wise library. + +## Collect web content + +You can collect online content, including web articles, videos, podcasts, using the LarePass browser extension, or the mobile client. + +### Collect via the LarePass extension + +::: tip Uploading cookies for better experience +Some websites restrict access for anonymous users. In such cases, you can upload your cookies to Olares for better experience. + +1. Log into the website, open the LarePass extension. +2. Go to **Collect** > **Cookie**, and click **Upload**. You can hover over cookies to view details. If you don't want to upload a specific cookie item, click **X** to unselect it. +::: + +To collect web content using the LarePass extension: + +1. Open the content page, for example, a CNN article. +2. Open the LarePass extension. The extension will automatically detect the collectable content on the page. + + ![Collect web content](/images/manual/tutorials/wise-collect-web-content.png#bordered) +3. In **Collect** > **Page**, click add_box next to the title to add the page to the Wise library. + +Once collected, you can find the content in **Library** > **Articles** in Wise. All media files, including audios, videos, and images on the page, will also be downloaded locally to the `/download/Wise/Article` directory. + +### Collect via the LarePass mobile client + +You can share web links to the LarePass mobile client for content collection. +:::info +The exact steps may vary depending on your operating system and browser. The following uses Safari as an example. +::: + +1. Tap **ios_shareShare** in the browser, then either: + - Select the LarePass icon in the sharing options, or + - Tap **LarePass** in **Other Actions** + + ![Share to Wise](/images/manual/tutorials/wise-add-articles-via-share.png#bordered) + + You will be redirected to the LarePass app. LarePass will automatically detect the collectable content on the shared page and prompt whether to add it to Wise. +2. Tap **Confirm** to add it to the Wise library. + +::: tip Copy URL to share +Alternatively, you can copy the URL directly and open LarePass. LarePass will automatically detect the URL in the clipboard and the collectable content as well. +::: + +Once added, you can find the content in **Library** > **Articles** in Wise. + +## Upload PDF/E-book content to Wise + +You can upload local PDF or EPUB e-books to Wise for centralized knowledge management. This allows you to keep your reading materials, notes, and related content in one place, making it easier to organize, search, and reference them whenever needed. + +1. Open **Wise**, click add_circle in the menu bar, and select **Upload**. +2. Navigate to the directory that contains the file you wish to upload, select the file, and click **Confirm**. + +View your PDFs under **Library** > **PDFs** and EPUBs under **Library** > **Books**. + +![View and manage PDF](/images/manual/tutorials/wise-pdf.png#bordered) + +::: tip +You can efficiently categorize and connect related content instantly with tags, or capture insights and ideas directly alongside the content using notes. For details, refer to [Organize your reading](../olares/wise/basics.md#organize-your-reading). +::: + +## Subscribe to RSS feeds +You can subscribe to podcasts, blogs, and your video playlists in Wise. New episodes or updates are automatically downloaded, ensuring you stay up-to-date without worrying about content being deleted or becoming inaccessible. Additionally, Wise can automatically download your favorite videos from platforms like YouTube, even for sources that aren't RSS-supported natively. + +### Subscribe via the LarePass extension + +To subscribe an RSS feed using the LarePass extension: + +1. Open the RSS page you want to subscribe to, for example, the "Paranormal Mysteries" podcast: `https://www.spreaker.com/podcast/paranormal-mysteries--2321086`. +2. Open the LarePass extension. It will automatically detect the RSS source on the page and show the **RSS** tab. + + ![Subscribe to podcast](/images/manual/tutorials/wise-sub-podcast.png#bordered) +3. In the **RSS** tab, find the correct subscription source and click bookmark_add to subscribe. + +### Manually add an RSS source + +To manually add an RSS source to Wise: + +1. Copy the RSS subscription link, such as [https://hnrss.org/frontpage](https://hnrss.org/frontpage), an RSS feed for HackerNews frontliners. +2. In Wise, click add_circle in the menu bar, and select **RSS feed**. +3. Paste the URL. Wise will automatically detect the available RSS source. + + ![Manually add RSS](/images/manual/tutorials/wise-add-rss.png#bordered){width=50%} +4. Click **Add** to subscribe. + +### Automatically download videos + +In addition to regular RSS subscriptions, you can use the LarePass extension and Wise to automatically download videos from your playlist on video platforms. Here's how to do it on YouTube: + +1. Log into your YouTube account. +2. In LarePass extension, go to **Collect** > **Cookie**, and click **Upload** to upload the cookies to Olares. Olares needs the cookies of the site to access your subscription and download videos. + + ::: tip Enable Auto-Sync + Cookie data may expire. It is recommended that you enable the **Auto-Sync** feature in the Cookies page to ensure your cookies are updated automatically each time you visit the site. + ::: +3. Under the video you want to watch, click more_horiz, select **Save**, and then click **Create New Playlist**. For example, `Save to Wise`. +4. Enter your playlist. The LarePass extension will automatically detect the available RSS feeds and show the **RSS** tab. +5. In the **RSS** tab, select the RSS feed with a link starting with `https://www.youtube.com/feeds/...` and click bookmark_add to subscribe. + + ![Subscribe to YouTube playlist](/images/manual/tutorials/wise-youtube-rss.png#bordered) + +Wise will automatically download all the videos saved to this playlist. + +::: tip Download videos from a specific channel +You can use LarePass extension similarly on your favorite YouTuber's channel. Once you get the corresponding RSS feed and subscribe to it, Wise will automatically download all the videos in the channel. +::: + +### Access your RSS content + +To access your RSS content in Wise: +1. From the left-hand menu bar, navigate to **Subscriptions** > **Feeds**. +2. Select an unread RSS item and enter it to watch the video, listen to the podcast, or simply read the article. + +![Access RSS](/images/manual/tutorials/wise-access-rss.png#bordered) + +::: tip Smart content recommendations +In addition to regular RSS subscriptions, Wise offers a fully local, privacy-protected intelligent content recommendation system. You can download the recommended algorithms from the Olares app market. Learn more in [Discover themed content](../olares/wise/recommend.md). +::: + +## Search through collected content + +## Learn more + +- [Wise basics](../olares/wise/basics.md) +- [Discover themed content](../olares/wise/recommend.md) +- [Subscribe and manage feeds](../olares/wise/subscribe.md) + diff --git a/docs/manual/best-practices/set-custom-domain.md b/docs/manual/best-practices/set-custom-domain.md new file mode 100644 index 000000000..c1c9d30ca --- /dev/null +++ b/docs/manual/best-practices/set-custom-domain.md @@ -0,0 +1,272 @@ +--- +outline: [2, 3] +description: Step-by-step guide to setting up a custom domain for your Olares environment. Learn how to add and verify domains, create organizations, configure member access, and create Olares IDs under your domain. +--- + +# Set up a custom domain for your Olares + +By default, when you create an account in LarePass, you get an Olares ID with the `olares.com` domain. This means you access your Olares services through URLs like `desktop.{your-username}.olares.com`. While this default setup saves you from common network and domain configuration hassles, you might want use your own domain instead, especially in these common scenarios: + +- **As an organization**: Use a company domain similar to your organizational email address for all team members, for example, `employee@company.com`. +- **As an individual**: Use your personal domain for a more personalized experience. + +This tutorial walks you through setting up your own domain for your Olares. + +## Objectives +In this tutorial, you will learn how to: +- Add and verify your custom domain in Olares Space +- Create an organization to manage your custom domain +- Configure member access for your organization +- Create an Olares ID under your custom domain +- Install and activate Olares with your Olares ID + +## How custom domains work in Olares +Custom domains in Olares are managed through organizations. This means whether you're an individual user or representing a company, you'll need to set up an organization first. The organization serves as the container for your custom domain configuration. + +The table below outlines the steps involved in setting up a custom domain and who is responsible for each task. Depending on whether you're an individual user or part of an organization, the actions you need to perform will differ. + +| Step | Individual user | Organization admin | Organization member | +|---------------------------------------------|-----------------|--------------------|---------------------| +| Create a DID | ✅ | ✅ | ✅ | +| Add domain to Olares Space | ✅ | ✅ | | +| Create organization for the domain | ✅ | ✅ | | +| Add email to the organization | ✅ | ✅ | | +| Join the organization & create an Olares ID | ✅ | ✅ | ✅ | +| Set up Olares | ✅ | ✅ | ✅ | + +## Before you begin + +Ensure you have: +- A registered domain name from a domain registrar. +- A Gmail or G-Suit account. Currently, only these two formats are supported for organization domain membership. +- LarePass app installed on your phone.
+ LarePass will be used later to sign in to Olares Space, and to bind your custom domain to Olares ID. + +## Step 1: Create a DID + +A DID (Decentralized Identifier) is a temporary account state before you get your final Olares ID. You can only bind a custom domain to the account when it is in the DID stage. To create one: + +1. In the LarePass app, go to the account creation page. + +2. Tap **Create an account** to trigger a DID creation. + + ![create DID](/images/manual/tutorials/create-a-did.png) + + This gets you an Olares account in the DID stage. + + ![DID stage](/images/manual/tutorials/did-stage.png) + +## Step 2: Add your domain to Olares Space +Add and verify your own domain in Olares Space before binding it. + +1. In your browser, access Olares Space at https://space.olares.com/. +2. In LarePass app, tap the scan button in the top-right corner, and scan the QR code on the login page to log in to Olares Space. + + ![scan QR](/images/manual/tutorials/scan-qr-code.png) + +3. In Olares Space, go to **Domain Management** > **Domain Name Setup**, enter your domain and click **Confirm**. + + ![add domain](/images/manual/tutorials/add-domain.png#bordered) + +4. Verify your TXT record for your domain. This verifies your ownership of the domain. + + a. Click **Guide** in the **Action** column. + + b. Follow the on-screen instructions to add a TXT record to your DNS provider configuration. + + ![verify TXT](/images/manual/tutorials/verify-txt.png#bordered) + + Once verified, the domain setup status will update automatically to **Await NS Record for Your Domain**. +5. Verify the Name Server (NS) Record for your domain. This delegates the DNS resolution for your domain to Olares's Cloudflare. + + a. Click **Guide** in the **Action** column. + + b. Follow the on-screen instructions to add the NS record to your DNS provider configuration. + + Once verified, the domain status will update to **Awaiting the application for the domain's Verifiable Credential**. + + ![domain added](/images/manual/tutorials/domain-added.png#bordered) + +:::info +TXT verification typically completes within 30 minutes. NS record verification may take up to 2 hours. If the whole process exceeds 3 hours, check with your DNS provider. +::: + +Once TXT and NS records are verified, your domain is successfully added to Olares Space. + +## Step 3: Create an org for the domain + +This step creates an organization for the domain. Specifically, it binds your domain to an organization in Olares and requests the Verifiable Credential (VC) for the domain. + +::: tip Verifiable Credential +A Verifiable Credential is a digital format proof that verifies certain attributes or qualifications of its holder without revealing additional personal information. +::: + +1. Create a new organization in LarePass app. + + a. On the account creation page, tap display_settings in the top-right corner to go to the **Advanced account creation** page. + + b. Go to **Organization Olares ID** > **Create a new organization**. The organization for your domain will automatically show in the list. + + ![Create org](/images/manual/tutorials/create-org.png) + + c. Tap the organization name to apply for the VC. When it's done, you will see your domain name for confirmation. + + d. Click **Confirm** to finish the organization domain binding in LarePass. + + ![Bind org](/images/manual/tutorials/bind-domain-with-org.png) + +2. On Olares Space, navigate to the **Domain management** page. The domain setup status should change to **Awaiting rule configuration**. + +So far, you have successfully bound your custom domain with an organization, and is set for configuring the domain rules in Olares Space. + +## Step 4: Add new member + +The domain rules specify how you add the members for the organization. Only members in the organization can apply for Olares ID under the organization domain (or, your custom domain). To configure domain rules: + +1. In Olares Space, go to **Domain management**, and click **View** next to your domain. +2. Under **Domain Invitation Rule**, select **Specified email address**, and click **Save**. + :::tip Invitation rules + Two types of rules are available: + - **Fixed email suffix**: Suitable for large teams who share the same corporation email domain (e.g., `@company.com`). Any email matching the specified suffix is valid to apply for Olares ID under the organization. Currently, only single suffix is supported. Must follow G-Suite format. + - **Specified email address**: Allows you to add members by specifying their email addresses. This option is recommended if you do not have a corporate email domain and only need to invite a small number of members to your organization. Both Gmail and G-Suite accounts are supported. + ::: + +3. Click **Add New User** and enter the Gmail address for the member. For example, `justtest1953@gmail.com`. + + ![Configure domain rules](/images/manual/tutorials/set-domain-rule.png#bordered) + +4. Click **Submit** to finalize the member addition. Repeat step 3 and step 4 if you want to add multiple users + +:::tip Maintain member list +For organization admin, you can manage your organization's member list anytime through the **Domain management** page. +::: + +## Step 5: Create an Olares ID with the custom domain + +To use the domain, apply for an Olares ID under the organization. + +1. On the account creation page of LarePass app, tap display_settings in the top-right corner to go to the **Advanced account creation** page. +2. Tap **Organization Olares ID** > **Join an existing organization**. +3. Type the org domain name (the verified custom domain) and click **Continue**. If you see an error, verify if the domain name is correct and the domain rules are set properly in Olares Space. +4. Add a VC for the member. + + a. When prompted, select Google as your VC credential provider. + + b. Log in with the Gmail account you added in the previous step and grant access for VC. + + ![Join the org](/images/manual/tutorials/join-org.png) + + After successful authorization, an Olares ID with the custom domain, `justtest1953@xxxx.cloud`, is successfully created. + +## Step 6: Install and activate Olares +Almost there! Now you are all set to install and activate Olares with your Olares ID. + +::: tip Install with environment variables +In the following examples, the domain name and username are preset with environment variables. + +For Linux environment, you can also install with the one-line script without these variables, and enter the domain and the prefix of Olares ID manually. + +For detailed instructions on all supported platforms, refer to [platform-specific installation guides](../get-started/install-olares.md). +::: + + + + + + +After completing these steps, your Olares installation will be accessible via your custom domain. + +## Learn more + +- [Olares account](../concepts/account.md) +- [Install Olares](../get-started/install-olares.md) +- [Configure domain rules](../../space/manage-domain.md) \ No newline at end of file diff --git a/docs/manual/best-practices/wise.reusables.md b/docs/manual/best-practices/wise.reusables.md new file mode 100644 index 000000000..389acca9d --- /dev/null +++ b/docs/manual/best-practices/wise.reusables.md @@ -0,0 +1,32 @@ +--- +search: false +--- +Once you've collected your content in Wise, you can search for particular content themes or entries using aggregated search in Olares. + +![Search in Wise](/images/manual/tutorials/wise-search.png#bordered) + +::: info Supported search formats +Currently, only document-type content (PDF, web articles, and ePUB) is searchable. Other formats will be supported in the future. +::: + +1. Click searchin the Dock to open the search window. +2. Specifies the search scope to Wise, and enter the keywords to search. + +:::info +The exact steps may vary depending on your operating system and browser. The following uses Safari as an example. +::: + +1. Tap **ios_shareShare** in the browser, then either: + - Select the LarePass icon in the sharing options, or + - Tap **LarePass** in **Other Actions** + + ![Share to Wise](/images/manual/tutorials/wise-add-articles-via-share.png#bordered) + + You will be redirected to the LarePass app. LarePass will automatically detect the collectable content on the shared page and prompt whether to add it to Wise. +2. Tap **Confirm** to add it to the Wise library. + +::: tip Copy URL to share +Alternatively, you can copy the URL directly and open LarePass. LarePass will automatically detect the URL in the clipboard and the collectable content as well. +::: + +Once added, you can find the content in **Library** > **Articles** in Wise. \ No newline at end of file diff --git a/docs/manual/concepts/account.md b/docs/manual/concepts/account.md new file mode 100644 index 000000000..dd790cf05 --- /dev/null +++ b/docs/manual/concepts/account.md @@ -0,0 +1,71 @@ +--- +outline: [2, 3] +description: Core principles of Olares account system, including synchronization mechanisms, account stages and unified authentication. Covers multi-factor authentication and multi-device sync fundamentals. +--- + +# Olares account + +This document covers concepts and designs related to account system in Olares. + +## Account synchronization + +Accounts in LarePass, Olares, and Olares Space stay synchronized as described below: + +- Creating an Olares requires providing an Olares ID and activate it using the LarePass logged in with that Olares ID. +- To log into Olares Space, you need to scan a QR code with LarePass. + +## Understand the stage of account + +Each account has three stages. + +### Not bound to an Olares ID (DID stage) +An unbound account represents the initial stage where you have basic credentials created locally. This includes your mnemonic phrase, private key, and DID, but no Olares ID yet. + +During this stage, you can export and back up your mnemonic phrase and access Olares Space to request an organization domain name. + +However, importing to other LarePass clients isn't possible at this point. +:::tip +In the LarePass app, when you tap **Create an account**, your account enters the DID stage. +::: +### Bound to an Olares ID +When your account is bound to an Olares ID, the system records the connection between your Olares ID and DID on the blockchain. + +This enables you to request and activate an Olares through Olares Space. + +At this stage, you gain the ability to import your account to other devices using your exported mnemonic phrase, supporting unified authentication across applications. + +### Bound to an Olares +The final stage occurs when your account is linked to an Olares device. This enables full participation in the Olares ecosystem, including monitoring system resources for your device. + +## Unified account system + +Olares supports unified authentication for a multi-user system. + +1. After the user logs in on the login page, all future requests automatically include authentication details. +2. Each user request first goes through the Authelia service for authentication. +3. If authentication fails, the application redirects the user to the login page to re-authenticate. +4. If authentication succeeds, the [Backend for Launcher (BFL)](https://github.com/beclab/bfl) attaches the user's basic information and forwards the request to the application service. This relieves the application from handling the authentication itself. +5. For [shared applications](./application.md#shared-applications), developers need to build an additional `Auth Server` to connect the application's account with the BFL account. + +## Multi-factor authentication (MFA) + +Olares integrates a variety of authentication factors with different security levels to ensure the security of user identity authentication in the system. + +### Password + +When a user is first created, Olares generates a random password for initial setup. After completing identity verification, the user is prompted to replace this initial password with a stronger, custom password. + +### One-time password + +When users perform sensitive operations such as login, Olares requires users to enter the one-time two-factor authentication code generated in LarePass. + +## Learn more + +### Users + +- [Create Olares ID](../get-started/create-olares-id) +- [User roles and permissions](../olares/settings/roles-permissions.md) + +### Developers + +- [Account system callback](../../developer/develop/advanced/account.md) \ No newline at end of file diff --git a/docs/manual/concepts/application.md b/docs/manual/concepts/application.md new file mode 100644 index 000000000..4e0c703eb --- /dev/null +++ b/docs/manual/concepts/application.md @@ -0,0 +1,129 @@ +--- +outline: [2, 3] +description: Fundamental concepts of Olares application system, explaining application identifiers and characteristics of four application types such as cluster-scoped applications. Includes service provider mechanisms and application dependencies. +--- + +# Applications + +This documents covers essential concepts for managing application identifiers, types, permissions, and Market integrations within Olares. + +## Application identifier + +In Olares, each application is assigned two identifiers: an application name and an application ID. + +### Application name + +Application names are assigned by Indexers. The official Indexer address maintained by Olares is [apps](https://github.com/beclab/apps). The directory name of an application within this repository serves as the application name. + +### Application ID + +The application ID is derived as the first eight characters of the MD5 hash of the application name. For instance, if the application name is "hello", the application ID becomes "b1946ac9". + +Application IDs are utilized in endpoints. + +## Application types + +There are multiple types of applications in Olares. You can distinguish a specific application type according to the namespace shown in Control Hub. + +### System applications + +System applications encompass Kubernetes, Kubesphere, Olares components, and essential hardware drivers. The system-level namespaces include: + +``` +os-system +kubesphere-monitoring-federated +kubesphere-controls-system +kubesphere-system +kubesphere-monitoring-system +kubekey-system +default +kube-system +kube-public +kube-node-lease +gpu-system +``` +`os-system` is a component developed by Olares team. Cluster-level applications and various database middleware provided by the system are installed under this namespace. + +### User system applications + +Olares supports multiple users and provides two distinct namespaces for system applications accessible to Admin and Member users: + +- **user-space-{Local Name}** + + The `user-space` namespace is where system applications that users interact with daily are installed. These applications include: + - Files + - Settings + - Control Hub + - Dashboard + - Market + - Profile + - Vault + + These applications interact with each other while also calling system-level interfaces (such as Kubernetes' `api-server` interface). To ensure system security, Olares deploys them in isolated user-space namespaces and uses sandbox mechanisms to prevent malicious program attacks and unauthorized access. + +- **user-system-{Local Name}** + + System applications and user's built-in applications are generally restricted from direct access by third-party applications. + + However, if built-in applications or database clusters make specific service interfaces available through a [service provider](../../developer/develop/advanced/provider.md), community applications can request access by [declaring these permissions](../../developer/develop/package/manifest.md#sysdata). + + When such access is granted, the system routes these network requests through secure proxies in the `user-system` namespace, ensuring proper authentication and protection of resources. + +### Community applications + +Community applications are applications created and maintained by third-party developers. They encompass a wide range of purposes, from productivity tools and entertainment applications to data analysis utilities. + +The namespace of community applications consists of two parts: application name and the user's [local name](olares-id.md#olares-id-structure), for example: + +``` +n8n-alice +gitlab-client-bob +``` + +### Shared applications + +A **shared application** is a special category of community applications on Olares designed to provide unified, shared resources or services to all users within an Olares cluster. + +Key characteristics of shared applications include: + +* **Centralized management**: Only administrators can install the core service of a shared application. Administrators are responsible for installing, configuring, and hosting the app's service, resources, and runtime environment within the cluster. +* **Easy identification**: In Olares Market, shared applications are typically marked with a "Shared" label for easy identification. +* **Flexible access**: The method for accessing a shared application depends on the app's form: + * **Headless backend service**: For shared applications that typically run as a background service without a graphical UI (e.g., Ollama), users need to install a **reference application** to call the service. For example, users within the cluster can access the Ollama service via Open WebUI or LobeChat. + * **Complete application with built-in UI**: For shared applications that include a complete user interface and backend service themselves (e.g., ComfyUI Shared or Dify Shared), administrators and other users in the cluster can obtain the service access point by directly installing the shared application itself. + +### Reference applications + +Reference applications are applications that have been granted access to specific shared applications within Olares. They typically provide a user-friendly interface, allowing users to easily access the APIs or services exposed by the shared applications. + +For example, Open WebUI, LobeChat, and n8n are reference applications for Ollama. Dify Shared is the reference application of itself. + +### Dependencies + +Dependencies are prerequisite applications that must be present for certain applications to function properly. Before installing an application with dependencies, users must ensure all required dependencies are already installed in the cluster. + +### Service provider + +The Service Provider mechanism enables community applications to interact with system applications and services from other community applications. + +![Service Provider](/images/overview/olares/image3.jpeg) + +The mechanism consists of three procedures： + +1. Provider declaration: Developers must [declare their application as a provider](../../developer/develop/advanced/provider#define-provider) for specific service interfaces. + The system includes built-in Providers. + +2. Permission request: Applications seeking to use a service interface must explicitly [request provider access permissions](../../developer/develop/advanced/provider#request-permission-to-call-provider). + +3. Request handling: `system-server` services under `user-system` act as an agent that handles incoming requests and performs necessary permission validations. + + +## Learn more + +- User + + [Manage apps in Market](../olares/market.md)
+ +- Developer + + [Learn to develop applications on Olares](../../developer/develop/index.md)
diff --git a/docs/manual/concepts/architecture.md b/docs/manual/concepts/architecture.md new file mode 100644 index 000000000..cdd9395e9 --- /dev/null +++ b/docs/manual/concepts/architecture.md @@ -0,0 +1,24 @@ +--- +description: Overview of Olares BEC architecture, explaining distributed node implementation for data storage and security. Details three core components Olares ID, Olares OS and LarePass. +--- +# Architecture of Olares + +Olares introduces a next-generation decentralized Internet framework through its Blockchain-Edge-Client (BEC) architecture. BEC decentralizes data storage and enhances security by distributing information across suitable platforms. + +![BEC](/images/manual/concepts/network-topology.jpeg) + +- **Blockchain**: Storage of high-value data, including decentralized identifiers (DIDs) and transactions on the blockchain via smart contracts. This enables transparency, immutability, and enhanced discoverability of data. +- **Edge**: The decentralized web node for users, hosting personal data such as documents, chat logs, and photos on private edge servers. Data remains within the user’s control on the edge, ensuring privacy and local data sovereignty. +- **Client**: The identity wallet app that ensures users can securely manage their identities and interact with their self-hosted systems while maintaining ownership and privacy over their digital credentials. + +## Core components of Olares + +Corresponding to the BEC architecture, Olares comprises the following core components: + +- [**Olares ID**](https://docs.snowinning.com/protocol/overview.html): A decentralized identity and reputation system that integrates decentralized identifiers (DIDs), verifiable credentials (VCs), and reputation data. It enhances trust by enabling transparent and verifiable interactions within decentralized environments. +- [**Olares OS**](https://github.com/beclab/Olares): A comprehensive, self-hosted operating system designed for edge devices. It allows users to host and manage their own data and applications, transforming personal edge devices into robust, sovereign cloud systems. +- [**LarePass**](https://olares.com/larepass): A secure, unified interface software that connects users to their Olares systems. It offers key functionalities, including identity management, remote access, device management, and data storage, ensuring seamless interactions with Olares. + +## Learn more + +- [Self-sovereign network](https://docs.snowinning.com/protocol/network.html) \ No newline at end of file diff --git a/docs/manual/concepts/data.md b/docs/manual/concepts/data.md new file mode 100644 index 000000000..356d98a52 --- /dev/null +++ b/docs/manual/concepts/data.md @@ -0,0 +1,112 @@ +--- +outline: [2, 3] +description: Olares data management architecture, explaining file system types, application storage paths and database support. Covers technical specifications of JuiceFS, PostgreSQL, MongoDB and Redis. +--- + +# Data + +User data is usually stored in file systems and databases. Of the two, databases are built based on file systems. Here are our design philosophies with them: + +**For file systems**: + + Olares is designed for multi-node clusters. Therefore, developers need to consider the access to the file system when the program is scheduled to different nodes when developing applications. We want to shield these details from developers. + +**For databases**: + +- For common databases, developers only need to modify the configuration to complete the integration. +- Different users and applications can share physical database instances to save resource overhead. + +**For both**: + +- Data between different users and different applications are isolated from each other. +- Scalable and highly available. +- Capable of performing unified backup and restore at the system level. + +## File System Type + +### JuiceFS + +Olares OS uses [JuiceFS](https://juicefs.com) as the underlying multi-physical node shared file system solution. In this way, applications can obtain cross-node file access using the simplest HostPath PV method. This allows Pods to be freely scheduled in the cluster. + +As for the back-end object storage solution of JuiceFS, we also provide two solutions: S3 and MinIO. + +By default, Olares uses the local file system (FS) when installed locally. However, if the `--with-juicefs=true` option is specified when running the [`olares-cli prepare`](../../developer/install/cli/prepare.md) command, JuiceFS will be installed and used. Additionally, a MinIO instance will be set up as the backend storage. + +### Local disk + +In some application systems, intensive file system read and write operations may occur. These intensive file system read and write operations are often fragmented random reads and writes. In various existing distributed storage cluster solutions, for such intensive fragmented random read and write operations, it is very likely that I/O or CPU consumption will be too high (usually due to high I/O Wait). + +The best practice provided by Olares is to make full use of the node's local hard disk as a file buffer. Although the local hard disk of the node has limited capacity, it has high-speed read and write performance because it basically uses SSD hard disk. If the application reads and writes files, it will be buffered on the local hard disk of the node, and then written asynchronously to the distributed file system in batches. This can turn most of the fragmented random reads and writes into a few sequential reads and writes. This greatly improves system I/O efficiency. + +## Application Storage Path + +For applications, there are 3 different storage paths to deal with different usage scenarios. + +### UserData + +The `UserData` storage path stores files that change infrequently but require cross-application access, such as documents, photos, and videos. + +Applications can obtain access permissions to a directory under the Home directory by applying for [UserData](../../developer/develop/package/manifest.md#userdata) permissions in `OlaresManifest.yaml`. For example, you can request permissions to the Picture directory for PhotoPrism, and permissions to the Downloads directory for qBittorrent and Jellyfin. + +### AppData + +The `AppData` storage path stores data that does not change frequently but needs to span across nodes. For example, configuration files. + +Applications can apply for [AppData](../../developer/develop/package/manifest.md#appdata) permissions in `OlaresManifest.yaml`. + +### AppCache + +The `AppCache` storage path is allocated for applications that directly operate the disk with good performance. The disadvantage is that it cannot be accessed across nodes. For example, the system database, application log, and cache. + +Applications can apply for [AppCache](../../developer/develop/package/manifest.md#appcache) permissions in `OlaresManifest.yaml`. + +## [PostgreSQL](../../developer/develop/advanced/database.md#rds) + +As one of the most popular open-source relational databases, PostgreSQL has excellent performance and rich plug-in functions. Olares OS deploys PostgreSQL on the system along with the popular Citus distributed database plug-in. At the same time, its cluster is managed through the PG Operator in the TAPR component. Users can easily expand the number of PostgreSQL nodes, and back up or restore data along with the entire Olares system. + +If the PostgreSQL database application declared by the developer in the application is Distributed, then Olares will build its database on Citus, allowing the application to fully utilize the capabilities of the distributed PG database. + +## [MongoDB](../../developer/develop/advanced/database.md#nosql) + +MongoDB, as a representative of NoSQL, has a wide range of application scenarios in the Internet of Things field. By deploying [Percona Operator for MongoDB](https://github.com/percona/percona-server-mongodb-operator), developers have a cloud-native version of MongoDB cluster in Olares. + +Like PostgreSQL, Olares also manages MongoDB backup and restore in a unified manner. Users do not need to have any DBA technical capabilities to easily implement functions such as scheduled backup, incremental backup, and fixed-point restore. + +## [Redis](../../developer/develop/advanced/database.md#cache) + +There is no doubt that Redis can be regarded as the most popular memory cache software currently. It has rich instructions and derives a variety of data types based on Key-Value data. Many systems even use it as KV data storage. Olares OS also deploys a customized [Redis Cluster Operator](https://github.com/beclab/redis-cluster-operator) in the system, providing a cloud-native version of Redis Cluster. + +Olares also takes over the backup and restore of Redis Cluster. There is no need for users to provide any separate operation and maintenance operations for Redis Cluster. + +In addition, since Redis Cluster itself lacks a data isolation mechanism, Olares OS has also developed a proxy layer tool to implement the `namespace` mechanism of data. This isolation mechanism is completely transparent to developers. Developers do not need to do any special processing of data keys in their code. Data isolation between multiple applications and multiple users can be achieved with simple configuration in application chart. + +:::tip +The system uses the Redis Cluster version, which is different from the stand-alone version of Redis. It is recommended to read the official Redis documentation for reference. +::: + +## Backup + +Backup is the backup and restore module of Olares OS. + +It helps users backup the entire Olares to Olares Space, and also supports user-defined storage locations. + +Backup operations can be performed daily and weekly. The first backup of each backup plan is a full backup and serves as the first snapshot of the backup plan. Subsequent snapshots are incremental backups. + +Backup objects include: + +- Kubernetes configuration data, such as user information, application information, etc. +- Database data, such as Redis, MongoDB, PostgreSQL, etc. +- File system data, such as videos, pictures, and various documents uploaded by users through the Files application + +The Backup component also has data restoration capabilities. You can download a backup snapshot to a local server or Olares Space to restore a complete Olares by rebuilding Kubernetes, databases, and user personal information. + +## Learn more + +- User + + [Manage files](../olares/files/index.md)
+ [Back up and restore](../../space/backup-restore.md) + +- Developer + + [File upload](/developer/develop/advanced/file-upload.md)
\ No newline at end of file diff --git a/docs/manual/concepts/did.md b/docs/manual/concepts/did.md new file mode 100644 index 000000000..babb8eaa3 --- /dev/null +++ b/docs/manual/concepts/did.md @@ -0,0 +1,31 @@ +# Decentralized Identifier (DID) + +Decentralized Identifiers (DIDs), as defined by the [W3C](https://www.w3.org/TR/did-core/), are self-sovereign globally unique identifiers that are verifiable without centralized registry. A DID can refer to any subject (e.g., a person, organization, thing, data model, abstract entity, etc.) as determined by its controller. + +The primary objective of DIDs is to empower individuals and organizations with control over their identity information, enabling them to selectively and securely share this information without reliance on centralized authorities. + +## Structure of a DID + +A DID is structured as a text string that comprises three distinct components: + +- **DID URI Scheme Identifier**: This specifies the identifier's format. +- **DID Method Identifier**: This indicates the specific protocol or method used to create the DID. +- **DID Method-Specific Identifier**: This is a unique identifier specific to the method used. + +![DID Structure](/images/manual/concepts/did.png) + +## DID derivation + +In the context of the Olares ID, DIDs are self-generated using a mnemonic-based algorithm similar to blockchain addresses. The derivation process follows this sequence: + +> Mnemonic -> Private Key -> Public Key -> Blockchain Address on DID + +1. **Mnemonic**: A randomly generated string consisting of 12 words that serves as the basis for generating the private key. +2. **Private Key**: Derived from the mnemonic, this key is kept confidential and is essential for creating the public key and blockchain address. +3. **Public Key and Blockchain Address**: Both are generated from the private key and can be shared publicly. + +::: warning IMPORTANT +It is crucial to keep the private key and mnemonic secure and confidential to prevent unauthorized access and ensure recoverability. +::: + + diff --git a/docs/manual/concepts/faq.md b/docs/manual/concepts/faq.md new file mode 100644 index 000000000..f1f875a0d --- /dev/null +++ b/docs/manual/concepts/faq.md @@ -0,0 +1,17 @@ +--- +outline: [2, 3] +--- + +# FAQ + +## What is the relationship with WorldCoin? + +World ID is a privacy-preserving proof of personhood. It is issued by the **Worldcoin protocol**, allowing individuals to prove they are human to any verifier (including Web2 applications) while maintaining privacy through **zero-knowledge proofs**. + +From the perspective of the **Olares ID**, World ID is a type of **Verifiable Credential (VC)** that proves the holder is a "natural person." We plan to introduce World ID into **LarePass** in the future. For more details, please refer to the [Worldcoin website](https://worldcoin.org/). + +## What are the differences among DID Metadata, VC, and Reputation? + +- **DID Metadata** are DID related data stored on the **DID Registry**. It consists of declarations made by the entity about themselves. It serves as self-reported data. +- **Verifiable Credentials (VCs)** are issued by one entity about another, often encapsulating objective data such as age or educational qualifications. VCs are cryptographically secure and verifiable. +- **Reputation** aggregates subjective evaluations of an entity from various sources, allowing for a more nuanced interpretation that can incorporate potential inaccuracies, biases, or opinions. \ No newline at end of file diff --git a/docs/manual/concepts/index.md b/docs/manual/concepts/index.md new file mode 100644 index 000000000..4c498b932 --- /dev/null +++ b/docs/manual/concepts/index.md @@ -0,0 +1,23 @@ +--- +description: Core concepts documentation of Olares system, covering architecture design, identity authentication, application management, network configuration and data security fundamentals for developers. +--- +# Overview + +The Concepts section helps you learn about the parts of the Olares system and obtain a deeper understanding of how Olares works. Read this section as needed to: + +- Develop applications for Olares +- Manage system deployments +- Troubleshoot issues +- Optimize system performance + +Understand Olares with the following concepts: + +- [Architectural components](architecture.md) +- [Olares ID](./olares-id.md) +- [Account](./account.md) +- [Application](./application.md) +- [Network](./network.md) +- [Data](./data.md) +- [Secrets](./secrets.md) + + diff --git a/docs/manual/concepts/network.md b/docs/manual/concepts/network.md new file mode 100644 index 000000000..158bccb7e --- /dev/null +++ b/docs/manual/concepts/network.md @@ -0,0 +1,97 @@ +--- +description: Olares network architecture principles, covering application entrance types, local access mechanisms, endpoint configurations and internal network security policies. +--- +# Network + +Olares provides users with a barrier-free but secure and versatile network solutions. This documents covers the key networking concepts related to application access. + +## Entrance + +Each Olares application can have one or more entrances that serve as access points. There are three types of entrances: + +- **Public entrance** + + - Provides external services such as blogs, social media, etc. + - Accessible without authentication + - Basic security through Cloudflare + +- **Private entrance** + + - Provides services exclusively for individual users, families, or teams + - Suitable for readers, entertainment, productivity tools, desktop applications, etc. + - Requires [authentication](account.md#multi-factor-authentication-mfa) for access + +- **Internal entrance** + - Functions similarly to private entrance + - No authentication required when accessing applications through LarePass VPN + +## Acccess to private entrances via VPN + +Simply enable [LarePass VPN](/manual/larepass/private-network.md) on your device to securely and quickly access your private applications via their dedicated URLs (e.g., `https://vault.alice123.olares.com`). + +::: tip Note +If LarePass VPN is not enabled, requests to your private entrances will be routed through your reverse proxy tunnel to Olares, which may cause network latency and incur charges. +::: + +## Endpoints + +An endpoint is the access address or point where users interact with an application. Simply put, it's the URL you enter in your browser's address bar to access a specific Olares application or its features. + +A typical Olares application endpoint follows this format: + + https://{routeID}.{domain} + +For example: `https://vault.alice123.olares.com`, where + +- `vault` is the route ID for a system application. +- `alice123.olares.com` is derived from the Olares ID `alice123@olares.com`. + +## Route ID + +A route ID is a unique identifier used to identify specific applications or application entrances. The default route IDs are automatically generated by the system according to the following rules: + +- System applications + - Use predefined memorable Route IDs + - Examples: `desktop` (for Desktop), `market` (for Market) +- Community applications + - Use an 8-character random string + entrance index (starting from 0) + - Example: For an application with Route ID 92d76a13 and two entrances, the first entrance is `92d76a130`, and the access URL is `92d76a130.bob.olares.com` + +::: tip Note + +- The URL of the application is derived from Olares ID. +- Entrance index refers to the position of entrance in multiple entrances defined in [`OlaresManifest.yaml`](../../developer/develop/package/manifest.md). + ::: + +## Olares internal network + +Olares implements a layered proxy routing design in its gateway architecture. Traffic flows through multiple layers: + +`cluster` -> `user` -> `application` -> `service component`. + +![alt text](/images/overview/olares/image4.jpeg) + +Inside the application, Olares has multiple layers of security. + +- **Namespace isolation** + + - Each application operates in its exclusive namespace + - All resources are namespace-confined + - Applications cannot connect `ClusterRole` to `ServiceAccount` + - Cross-namespace resource access is prohibited + +- **Network policy controls** + - Each namespace has dedicated network policies + - Incoming network requests are restricted to cluster applications and system applications of the user + - User-level network isolation: + - Applications isolated between users + - Third-party applications isolated within user space +- **Pod restrictions** + - Pods cannot use `hostNetwork` service or `NodePort` service + - Traffic access requires declared entrance service and system-provided entry proxy + - The Pod declared as entrance will be forced to join Envoy's sandbox Sidecar to authenticate and authorize incoming traffic. + +## Learn more + +- [Set up custom domain name for application](../olares/settings/custom-app-domain.md#custom-domain-name) +- [Access Olares via VPN](/manual/larepass/private-network.md) diff --git a/docs/manual/concepts/olares-id.md b/docs/manual/concepts/olares-id.md new file mode 100644 index 000000000..219debcde --- /dev/null +++ b/docs/manual/concepts/olares-id.md @@ -0,0 +1,75 @@ +--- +description: Definition, structure and purpose of Olares ID system. Covers personal ID types, domain categories and relationship principles with decentralized identifiers (DID). +--- +# Olares ID + +This document introduces Olares ID, the foundation of identity and trust in the Olares ecosystem. + +## What is an Olares ID? + +An Olares ID is a decentralized identity and credit system that facilitates secure, trustless exchanges of information and value. It serves as your digital identity across the Olares ecosystem, enabling individuals and organizations to manage their identities independently—without reliance on third-party intermediaries. + +Each Olares ID is: + +- Unique, like an email address (e.g., alice123@olares.com). + +- Human-friendly, making it easy to remember and share. + +- Bound to a DID, ensuring cryptographic security and verifiability. + +## Why do you need an Olares ID? + +Your Olares ID powers seamless access, enhanced security, and a personalized experience within the Olares system. Key benefits include: + +* **Ease of access**: The system automatically provisions subdomains and access policies for your applications within Olares. You can use the domain name as your personal web address for seamlessly access from anywhere. +* **Free HTTPS certificate**: Olares domain name comes with a free HTTPS certificate, ensuring secure and encrypted communication for all your digital interactions. +* **Easy to remember and personalized**: Olares ID and the corresponding domain name are easy to remember, share, and personalized for your distinct online identity. + +For example, if your Olares ID is `alice123@olares.com`, Olares automatically assigns the following URLs: +- `alice123.olares.com`: Your personal homepage. +- `desktop.alice123.olares.com`: Access to your Olares Desktop. +- `files.alice123.olares.com`: Access to the Files app. + +## Olares ID structure +The format of an Olares ID is the same as an email address, consisting of two parts: +- A local name (prefix) +- A domain name (suffix) + +For example, in `alice123@olares.com`, *`alice123`* is the local name, and *`olares.com`* is the domain. + +Local names are unique within each domain, ensuring that each Olares ID is unique. + +### Domain types +Within Olares, there are three types of Domains: + +* Individual domain: For personal use, similar to personal email. Currently, Olares provides default domain `olares.com` for individual users. +* Organizational domain: For organizational use, like company email addresses. After joining an organization, users can apply for an Olares ID under that organization's domain. The administrator can revoke this Olares ID when the user leaves the organization. +* Entity domain: For applications and other entities that cannot be classified as either personal or organizational. + +### Olares ID creation for individuals +Olares offers two approaches to create an individual Olares ID: +- **Quick creation**
You can create an Olares ID by choosing an available name that meets the requirements. +- **Advanced creation**
+This approach uses Verification Credentials (VC) to connect an existing trusted identity (such as email accounts) with the Olares ID. +When creating a verified identity, Olares: + * Authenticates the user through established OAuth providers + * Creates cryptographic links between the social identity and Olares DID + +:::tip Create an Olares ID with Verifiable Credential (VC) +On the LarePass app, click display_settings, then select **Individual Olares ID**. + +Currently, verification is available through Google OAuth. +::: + +## What's Olares ID's relationship with DID +A Decentralized Identifier (DID) is a unique, cryptographically verifiable identifier that doesn't rely on any centralized authority. While DIDs solve the issue of identity in a decentralized network, they are typically difficult for humans to remember or use in daily situations. Learn more in [DID](did.md). + +Olares IDs makes DIDs more user-friendly. It provides a familiar, easy-to-remember format similar to email addresses, while still leveraging the power and security of DIDs. + +Each Olares ID is bound to a DID. When a user creates an account using Olares, a DID is created at the same time. Learn more about their relationship in [Stage of Olares account](./account#understand-the-stage-of-account). + +## Learn more + +* [Create an Olares ID](../get-started/create-olares-id) +* [Decentralized identifier (DID)](did.md) +* [Gmail issuer service](/developer/contribute/olares-id/verifiable-credential/olares.md#gmail-issuer-service) diff --git a/docs/manual/concepts/registry.md b/docs/manual/concepts/registry.md new file mode 100644 index 000000000..be2b9f047 --- /dev/null +++ b/docs/manual/concepts/registry.md @@ -0,0 +1,17 @@ +# DID Registry on Blockchains + +Once a DID is generated, users need to register their ownership in a **DID Registry**. Although the W3C standards do not prescribe a specific implementation for this registry, Olares ID utilizes [Smart Contracts](/developer/contribute/olares-id/contract/contract.md#smart-contract.md) to facilitate the registration process. This approach offers several advantages: + +- **Decentralization**: There is no reliance on centralized providers or authorities. +- **Censorship resistance**: The structure is robust against censorship and interference. +- **Universal discoverability**: DIDs can be easily discovered by users across the network. + +Issuers can upload essential DID metadata to the Registry, including the DID itself, [Olares ID](olares-id.md), RSA public keys, and other relevant information. + +DID metadata require minimal storage and infrequent updates. This allows existing mainstream blockchain technologies to manage these efficiently. Storing and retrieving DID metadata on blockchain results in low overhead and system efficiency. + +Currently, Olares ID's smart contracts are deployed on [OPTIMISTIC ROLLUPS](https://optimism.io/), an Ethereum Layer 2 blockchain. + +::: info +It is noteworthy that the Web5 development team has transitioned from utilizing ION as their registry mechanism to adopting a Distributed Hash Table (DHT) network. DHT networks provide a greater degree of decentralization compared to Layer 2 blockchain solutions. However, managing DHT networks involves complexities in maintaining efficiency and stability, as well as ensuring data integrity across a vast number of nodes. +::: \ No newline at end of file diff --git a/docs/manual/concepts/reputation.md b/docs/manual/concepts/reputation.md new file mode 100644 index 000000000..1b5577db8 --- /dev/null +++ b/docs/manual/concepts/reputation.md @@ -0,0 +1,47 @@ +# Autonomous Reputation System + +**DIDs** and **VCs** provide ways to identify yourself in a decentralized network, but how about ratings about others? This is where we need a reputation system. Reputation systems are very common in online platforms and communities. Consider the rating systems we use today, such as those found on popular review sites. + +- Online review platforms like Yelp, IMDB, etc. +- Financial scoring like [FICO Score](https://www.fico.com/en/products/fico-score), gather and aggregate claims to form a comprehensible reputation metric. + +## Problems with traditional reputation systems + +Reputation systems are designed to allow participants to assess the credibility and reliability of others, thereby facilitating meaningful engagement and value exchange. However, traditional reputation systems are limited in following aspects: + +- **Centralization:** User-generated ratings are stored opaquely in centralized databases, controlled by the platform. +- **Customization limitations**: Users cannot adjust how reputation metrics are calculated or select the reputation algorithms as needed. +- **Manipulation risk:** Some entities can exploit the system by paying for higher scores or better rankings, potentially distorting the reliability of these ratings. + +## Olares ID's decentralized approach + +The **Olares ID** aims to build a decentralized reputation system based on **DIDs** and **VCs**, ensuring transparency, control, and trust: + +![reputation](/images/manual/concepts/reputation.jpeg) + +- **Decentralized raw data collection:** + + User ratings are recorded directly on the blockchain through smart contracts, guaranteeing the authenticity and immutability of the data. + +- **Open Algorithms:** + + Unlike traditional systems, Olares ID allows reputation algorithms to be transparent. Algorithm providers openly publish their methods, giving users the option to choose which algorithms they trust for generating scores or rankings. + +- **Customized reputation processing:** + + Users can access the raw data and develop the insights based on their specific needs, ensuring a customized and fair reputation assessment. + +- **Reputation distribution:** + + Reputation insights are distributed via a specialized Market Protocol, enabling users to access decentralized, reliable reputation data from multiple sources based on their needs. + +## Entity domains for a autonomous reputation system + +In Olares ID, abstract entities don’t fall under traditional categories such as individuals or organizations but still need representation through DIDs. This is where entity domain comes into play. It enables abstract entities, such as movies, applications, or market makers, to have decentralized identities. + +The primary goal of entity domains is to support protocols in creating reputation systems for these abstract entities. With this feature, we envision the development of Web3 versions of platforms like IMDb, Yelp, and LinkedIn, fostering a true decentralized autonomous and dependable reputation system. + + + + + diff --git a/docs/manual/concepts/secrets.md b/docs/manual/concepts/secrets.md new file mode 100644 index 000000000..8d9efb0e2 --- /dev/null +++ b/docs/manual/concepts/secrets.md @@ -0,0 +1,26 @@ +--- +description: Olares secrets management system principles, detailing vault items, credentials, secrets and integration credentials classification. Explains sensitive data storage strategies. +--- +# Secrets + +Olares categorizes secrets based on usage scenarios and employs various management techniques. + +| | Data Type | Storage Location | Leak Risk | Usage | +|-------------|----------------------------------------------------------------------------------------------------------|-------------------------------------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| +| Vault items | Includes website and
database passwords,
blockchain private
keys, etc. | Vault | Encrypted data in Olares ensures that third parties cannot view even upon logging in | Each use requires a signature from LarePass | +| Credentials | System access
credentials obtained
post-secure
authentication:
Tokens, Cookies, etc. | [Infisical](https://infisical.com/) | Viewable by third parties post-authentication in Olares by following specific steps | Available to applications through an API after obtaining Provider permissions | +| Secret | Sensitive data used
in Pod containers,
like database
connections and
admin accounts | ETCD | Directly visible in [Control Hub](../olares/controlhub/navigate-control-hub#secrets) | Used in Helm deployment templates; secret values are injected into environment variables via valueFrom -> secretKeyRef | + +## Integration credential + +Users can enable applications within Olares to access external service credentials by logging into third-party service accounts through Settings. Examples include: + +- Logging in to Olares Space allows the backup service to request tokens for automated backend backups. +- Logging into Google enables Files to synchronize with data from Google Drive. + +Applications in Olares can retrieve these third-party service credentials via the [Service Provider](../../developer/develop/advanced/provider.md). + +## Application credential + +- Applications within Olares can manage and utilize [credentials](../../developer/develop/advanced/secret.md) via system-provided interfaces. +- Credentials generated by an application are exclusively restricted to that application's use. \ No newline at end of file diff --git a/docs/manual/concepts/self-sovereign-network.md b/docs/manual/concepts/self-sovereign-network.md new file mode 100644 index 000000000..58c99731b --- /dev/null +++ b/docs/manual/concepts/self-sovereign-network.md @@ -0,0 +1,41 @@ +# Self-Sovereign Network + +Leveraging [**DID**](did.md) and [**Blockchain Registry**](registry.md), we have established a self-sovereign peer-to-peer network using a Blockchain-Edge-Client (BEC) architecture. It eliminates the need for third-party trust, enabling direct information exchange and trustless value exchange between any two entities. + +## BEC architecture + +The BEC framework decentralizes data storage by distributing it across the appropriate locations. It is built on three pillars: + +- **Edge**: Users store personal data (e.g., documents, chat logs, photos) on their private edge servers. All user interactions, whether with other individuals or services, are facilitated through this server. Our instantiation of this component is Olares, the open source self-hosted operating system running on edge devices. + +- **Blockchain**: High-value data like DIDs and transactions are stored on the blockchain for transparency, security, and discoverability. Olares ID stores the DID Registry on Ethereum Virtual Machine (EVM) supported blockchains via smart contracts. + +- **Client**: The identity wallet app that enable users to maintain full control of their private keys stored on mobile devices. Our instantiation of this component is LarePass, the comprehensive client app of Olares. + +## Direct trustless information exchange through BEC + +We’ll demonstrate the BEC network topology using Alice and Bob, who have initially registered their DIDs on the blockchain. +Here are the steps when Alice sends a message to Bob through the BEC framework: + +![alt text](/images/manual/concepts/network-topology.jpeg) + +1. Alice sends the message from her terminal device to her **Edge server**. +2. Using the blockchain as a decentralized **Domain Name System (DNS)**, Alice’s Edge determines Bob’s Edge location. +3. Alice’s Edge forwards the message to Bob’s Edge. +4. Bob’s Edge verifies the authenticity of the message by validating Alice’s cryptographic signature against the blockchain, similar to how a **Certificate Authority (CA)** functions. +5. Once validated, the message is securely relayed from Bob's Edge to his terminal device. + +## Trustless value exchange via Otmoic + +The **Otmoic** protocol is a trustless automatic value-exchange protocol built on the **Olares ID**. +It is designed to provide **public goods** with a fair price, ensuring transparency and decentralized value exchange. Key features include: + +![alt text](/images/manual/concepts/rfq.jpeg) + +- **On-chain Reputation Mechanism**: Implements a reputation system for traders and liquidity providers, addressing the **free mint problem**. +- **KYC Support via Verifiable Credentials**: Ensures identity verification without compromising decentralization. +- **RFQ-Based Price Discovery**: Allows for efficient **Request-for-Quote** (RFQ) driven price discovery. +- **Atomic Swap Support**: Facilitates trustless, on-chain atomic swap transactions. +- **Automatic Market Making**: Liquidity providers can engage in automatic market-making by installing applications on **Olares**. + + diff --git a/docs/manual/concepts/vc.md b/docs/manual/concepts/vc.md new file mode 100644 index 000000000..a8ec988c5 --- /dev/null +++ b/docs/manual/concepts/vc.md @@ -0,0 +1,46 @@ +# Verifiable Credential + +DIDs represent both tangible or intangible entities across physical and digital realms. Each entity can have multiple claims, and the documents that support these claims are called **Verifiable Credentials (VCs)**. VCs are fully ratified W3C standard designed to work together with DIDs to enable trustless, secure interactions. + +Consider this example: Alice, an entity, has educational qualifications that form a claim. Her diploma acts as the credential that verifies this claim. The diploma is issued by the university she attended and can be securely authenticated using cryptographic methods. When Alice applies for jobs, potential employers can verify this credential during interview. + +## Roles related to VC + +The following outlines the transformation of a diploma from a simple credential to a VC: + +![Verifiable Credential Process](/images/manual/concepts/vc-diploma.jpeg) + +This process involves three roles: + +- **Issuer** + + > A role an entity can perform by asserting claims about one or more subjects. It creates a verifiable credential from these claims, and transmit the verifiable credential to a holder. + + In the above example, the Issuer is the university Alice attended. + +- **Holder** + + > Holders are entities that have one or more verifiable credentials in their possession. Holders are also the entities that submit proofs to Verifiers to satisfy the requirements described in a Presentation Definition. + + In this case, the Holder is Alice. She stores and manages her VCs using a wallet app, which is TermiPass in this case. + +- **Verifier** + + > Verifiers are entities that define what proofs they require from a Holder via the Presentation Definition in order to proceed with an interaction. + + The Verifier in this scenario is the company Alice interviews with. + +## Verification process + +The verification process involves six structured steps: + +1. The Issuer registers their information on the DID Registry. +2. The Holder submits a verification request to the Issuer, indicating the need for credential issuance. +3. The Issuer issues a VC to the Holder, embedding a claim about her educational qualifications. +4. The Holder securely stores this VC in TermiPass, ensuring its availability for future verification. +5. The Holder sends a **Verifiable Presentation (VP)** that encapsulates the VC to a Verifier, initiating the verification process. +6. The Verifier checks the authenticity of the VC's and VP's signatures via the DID Registry, confirming the validity of the claim, thereby completing the verification. + +::: tip NOTE +VCs are not stored on the blockchain. +::: \ No newline at end of file diff --git a/docs/manual/concepts/wallet.md b/docs/manual/concepts/wallet.md new file mode 100644 index 000000000..96532a14f --- /dev/null +++ b/docs/manual/concepts/wallet.md @@ -0,0 +1,28 @@ +# Identity Wallet App + +A Digital Identity Wallet is an essential tool in the self-sovereign identity ecosystem, allowing users to manage their decentralized identifiers (DIDs), credentials, and interactions with digital services, without relying on centralized entities for authentication or data sharing. + +LarePass is the identity wallet app for Olares, the decentralized self-hosted OS based on Olares ID. LarePass allows users easily and securely manage DIDs, Olares IDs, and enables seamless access to Olares. + +## Manage Olares ID + +When users creates a Olares account, a DID is automatically generated in the beginning and then bound to the new Olares ID. LarePass facilitates the Olares ID management with the following functions: + +![Olares ID management](/images/manual/concepts/create-terminus-name.png) + +- Olares IDs creation + - Fast creation without VC binding + - Advanced creation with VC binding (via the Gmail Issuer service) +- Backup/Import Olares IDs with a mnemonic phrase for quick setup and account recovery +- Manage multiple DIDs/Olares IDs + +See [Manage Accounts with LarePass](https://docs.olares.com/how-to/LarePass/account/) for more detailed information. + +## Manage VCs + +LarePass allows users to manage their VCs that are bound to Olares IDs, enabling users to interact with VCs through signing, verification, discovery, and presentation processes. + +![VC management](/images/manual/concepts/vc-management.png) + +::: tip NOTE +These are just the core implementations of LarePass that are closely related to the identity wallet. For more details on LarePass and its usages, refer to the [LarePass documentation](https://docs.olares.com/how-to/LarePass/overview.html). diff --git a/docs/manual/docs-home.md b/docs/manual/docs-home.md new file mode 100644 index 000000000..f4f3a012c --- /dev/null +++ b/docs/manual/docs-home.md @@ -0,0 +1,77 @@ +--- +description: Learn about Olares, an open-source sovereign cloud OS for local AI. Discover how to self-host services, run AI applications, manage files, and collaborate securely with enterprise-grade features. +--- +# Olares documentationDev +::: warning Note on Dev version +This documentation provides a preview of features for an upcoming Olares version. As this is not a stable release, the features and user interface described here may be unstable, incomplete, and are subject to change. +::: + +## What is Olares? + +Olares is an open-source personal cloud operating system designed to empower you to own and manage your digital assets locally. Instead of relying on public cloud services, you can deploy powerful open-source alternatives locally on Olares, such as Ollama for hosting LLMs, SD WebUI for image generation, and Mastodon for building censor free social space. Imagine the power of the cloud, but with you in complete command. + +With Olares, self-hosting is no longer a daunting task. It simplifies complex processes like network setup, domain management, and service orchestration, enabling both beginners or experienced users to focus on what truly matters. + +Privacy and independence are at the core of Olares. It is perfect for individuals or teams who want to avoid relying on centralized platforms. Your data stays on your hardware, and all tasks are processed locally, so your sensitive information never leaves your control. Olares gives you complete ownership of your data and infrastructure without sacrificing performance or simplicity. + +
+ +
+

New to Olares?

+

Check out the get-started guide to set up Olares on your local machine

+
+
→
+ +
+ +## Highlighted features + +Olares offers a wide array of features designed to enhance security, ease of use, and development flexibility: + +- **Enterprise-grade security**: Secure your self-hosted cloud with simplified network configuration using Tailscale, Headscale, Cloudflare Tunnel, and FRP. +- **Secure and permissionless application ecosystem**: Access nearly 100 free applications in a secure, sandboxed environment. [See what Olares Market has to offer](https://market.olares.com/). +- **Unified file system and database**: Support automated scaling, backups, and high availability. +- **Single sign-on**: Log in once to access all applications within Olares with a shared authentication service. +- **AI capabilities**: Manage GPU resources, host AI models locally, and build private knowledge bases with complete privacy. +- **Built-in applications**: Get started with essential pre-installed applications such as Files, Vault, Wise, Profile and Dashboard. +- **Seamless anywhere access**: Access your devices from anywhere using dedicated clients for mobile, desktop, and browsers. +- **Development tools**: Build and port applications easily with comprehensive development tools. + +## Key use cases + +- 🖥️ **Homelab server**: Turn your personal devices into a versatile homelab for experimenting with containerized applications, running local AI models, managing self-hosted services, or testing cloud technologies—all within your own private infrastructure. + +- 🤖 **Local AI**: Host and run cutting-edge open-source AI models—including large language models, image generation, and speech recognition—directly on your devices. Build custom AI assistants that integrate with your data and applications while keeping everything private and secure. + +- 💻 **Personal data repository**: Securely store, sync, and manage your photos, documents, and important files in a unified, private storage system accessible from anywhere. + +- 🛠️ **Self-hosted workspace**: Create a free, collaborative workspace for your team or family with open-source alternatives to commercial productivity tools. + +- 🎥 **Private media server**: Turn your personal media collection into your own streaming service, hosted entirely on your devices. +- 🏡 **Smart home**: Use Olares as the central control point for managing IoT devices and home automation. +- 🤝 **Decentralized social media**: Host decentralized social media platforms like Mastodon, Ghost, or WordPress to build your personal brand without the risks of bans or platform fees. + +## Pick your path + +Before you roll up your sleeves and get your hands dirty with Olares, feel free to take a quick tour. Here are some alternative paths to get a feel for what Olares can do. + +
+ +

Explore use cases

+

Discover real-world applications and see how Olares solves common challenges.

+ + +

Learn how-tos

+

Comprehensive system app guides covering daily tasks of using Olares.

+ + +

Understand Olares

+

Grasp the fundamental principles and architecture behind Olares.

+ +
+ +## Other resources + +- [Develop Olares apps](../developer/develop/) +- [Join our community on Discord](https://discord.com/invite/BzfqrgQPDK) +- [Check out Olares blogs](https://blog.olares.com/) \ No newline at end of file diff --git a/docs/manual/feature-overview.md b/docs/manual/feature-overview.md new file mode 100644 index 000000000..66abac790 --- /dev/null +++ b/docs/manual/feature-overview.md @@ -0,0 +1,30 @@ +# Feature comparison +:::tip Legend +- 🚀: **Auto**, indicates that the system completes the task automatically. +- ✅: **Yes**, indicates that users without a developer background can complete the setup through the product's UI prompts. +- 🛠️: **Manual Configuration**, indicates that even users with an engineering background need to refer to tutorials to complete the setup. +- ✖️: **No**, indicates that the feature is not supported. +::: + +| | Olares | Synology | TrueNAS | CasaOS | Unraid | +|---------------------------|------------------------------------------------------------------------------------------------------------|---------------------------------------------|---------------------------------------------|-------------------------|-----------------------------------------------| +| Multi-node | ✅ | ✖️ | ✅ | ✖️ | ✖️ | +| Build-in apps | ✅ (Rich desktop apps) | ✅ (Rich desktop apps) | ✖️ (CLI) | ✅ (Simple desktop apps) | ✅ (Dashboard) | +| Free domain name | ✅ | ✅ | ✖️ | ✖️ | ✖️ | +| Auto SSL certificate | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | +| Reverse proxy | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | +| VPN management | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| Graded app entrance | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| Multi-user management | ✅ User management
🚀 Resource isolation | ✅ User management
🛠️ Resource isolation | ✅ User management
🛠️ Resource isolation | ✖️ | ✅ User management
🛠️ Resource isolation | +| Single login for all apps | 🚀 | ✖️ | ✖️ | ✖️ | ✖️ | +| Cross-node storage | 🚀 (Juicefs+
MinIO) | ✖️ | ✖️ | ✖️ | ✖️ | +| Database solution | 🚀 (Built-in cloud-native solution) | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| Disaster recovery | 🚀 (MinIO's [**Erasure Coding**](https://min.io/docs/minio/linux/operations/concepts/erasure-coding.html)) | ✅ RAID | ✅ RAID | ✅ RAID | ✅ Unraid Storage | +| Backup | ✅ App Data
✅ User Data | ✅ User Data | ✅ User Data | ✅ User Data | ✅ User Data | +| App sandboxing | ✅ | ✖️ | ✖️ (K8S's namespace) | ✖️ | ✖️ | +| App ecosystem | ✅ (Official + third-party) | ✅ (Majorly official apps) | ✅ (Official + third-party submissions) | ✅ Majorly official apps | ✅ (Community app market) | +| Developer friendly | ✅ IDE
✅ CLI
✅ SDK
✅ Doc | ✅ CLI
✅ SDK
✅ Doc | ✅ CLI
✅ Doc | ✅ CLI
✅ Doc | ✅ Doc | +| Local LLM hosting | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| Local LLM app development | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| Client platforms | ✅ Android
✅ iOS
✅ Windows
✅ Mac
✅ Chrome Plugin | ✅ Android
✅ iOS | ✖️ | ✖️ | ✖️ | +| Client functionality | ✅ (All-in-one client app) | ✅ (14 separate client apps) | ✖️ | ✖️ | ✖️ | \ No newline at end of file diff --git a/docs/manual/get-started/activate-olares.md b/docs/manual/get-started/activate-olares.md new file mode 100644 index 000000000..07f008b5e --- /dev/null +++ b/docs/manual/get-started/activate-olares.md @@ -0,0 +1,38 @@ +--- +search: false +--- +## Activate Olares + +Use the Wizard URL and initial one-time password to activate. This process connects the Olares device with your Olares ID using LarePass. + +1. Enter the Wizard URL in your browser. You will be directed to the welcome page. Press any key to continue. + + ![Open wizard](/images/manual/get-started/open-wizard.png#bordered) +2. Enter the one-time password and click **Continue**. + + ![Enter password](/images/manual/get-started/wizard-enter-password.png#bordered) +3. Select the system language. + + ![Select language](/images/manual/get-started/select-language.png#bordered) +4. Activate Olares using LarePass app. + + a. Open LarePass app, and tap **Scan QR code** to scan the QR code on the Wizard page and complete the activation. + :::warning Same network required + To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network. + ::: + + ![Activate Olares](/images/manual/get-started/activate-olares.png#bordered) + + b. Reset the login password for Olares by following the on-screen instructions on LarePass. + + ::: tip Reactivate Olares with the same Olares ID + + If you have reinstalled Olares, the original instance becomes unavailable. To reactivate Olares with the same Olares ID: + + 1. Open LarePass on your phone, and you can see a red prompt: "No active Olares found". + 2. Tap **Learn more**, then **Reactivate** to enter the QR scan page. + 3. Tap **Scan QR code** to scan the QR code on the wizard page and activate Olares. + ::: + + +After successful setup, the LarePass app will automatically go to the home screen, and the Wizard will redirect you to the login page. \ No newline at end of file diff --git a/docs/manual/get-started/create-olares-id.md b/docs/manual/get-started/create-olares-id.md new file mode 100644 index 000000000..cf83fb26a --- /dev/null +++ b/docs/manual/get-started/create-olares-id.md @@ -0,0 +1,51 @@ +--- +description: Step-by-step guide to creating your Olares ID using LarePass mobile app. +--- +:::warning Note for Mainland China users +The steps in this guide differ for users in Mainland China due to regional differences. For a version tailored to your region, please read the Simplified Chinese documentation. +::: +# Create Olares ID + +An Olares ID is a unique identifier within the Olares ecosystem, serving as your digital identity and gateway to various services and features. + +An Olares ID consists of a local name and a domain. For example, in `alice123@olares.com`: +- `alice123`: Local name +- `olares.com`: Domain name + +:::tip Olares ID with custom domain +To create an Olares ID with your custom domain, see [Set up a custom domain for your Olares](../best-practices/set-custom-domain.md). +::: +## Download and install LarePass app + +To get started with Olares, you'll need to download LarePass on your mobile device. LarePass is available for both Android and iOS platforms: + +* **For Android users**: Install LarePass from the Google Play Store. +* **For iOS users**: Download LarePass from the App Store. + +## Create an Olares ID + +::: tip +This section focuses on creating individual Olares IDs. If you want to create an Olares ID for organizational uses, or use a custom domain, refer to [Set up a custom domain](../../space/host-domain.md). +::: + +1. In the LarePass app, tap **Create an account**. +2. Enter your desired Olares ID. It must meet the following requirements: + * never be registered before + * at least 8 characters long + * only lowercase letters and numbers +3. Click **Continue** to finish the creation process. + +![Fast creation](/images/manual/get-started/create-olares-id.png) + +## Next step + +Keep your newly created Olares ID and LarePass app handy – you'll need them later. + +To install and activate Olares as an administrator: +- [Install Olares](./install-olares) + +If your team already has Olares, and you're joining as a member: +- [Activate Olares](./activate-olares) + +If you wish to log in to Olares Space, or creating a cloud-based Olares: +- [Manage accounts in Olares Space](../../space/manage-accounts) \ No newline at end of file diff --git a/docs/manual/get-started/index.md b/docs/manual/get-started/index.md new file mode 100644 index 000000000..e01c8a1e0 --- /dev/null +++ b/docs/manual/get-started/index.md @@ -0,0 +1,38 @@ +--- +description: Choose your path to begin using Olares for personal or team use. +--- +# Get started +Welcome to Olares! This guide will help you quickly set up and start using Olares on your preferred platform. +::: tip +If you prefer to try the cloud version of Olares instead of self-hosting, refer to the [Olares Space documentation](../../space/). +::: + +
+ +
+

First time using Olares?

+

Learn how to create an Olares ID, and get your Olares up and running.

+
+
→
+ +
+ +
+ +
+

Already have an Olares?

+

Explore our comprehensive how-to guide covering every aspect of Olares.

+
+
→
+ +
+ +
+ +
+

Ready to get productive with Olares?

+

Explore our use cases and tutorials to see how Olares can streamline your workflow and unlock new possibilities.

+
+
→
+ +
\ No newline at end of file diff --git a/docs/manual/get-started/install-and-activate-olares.md b/docs/manual/get-started/install-and-activate-olares.md new file mode 100644 index 000000000..70aff6294 --- /dev/null +++ b/docs/manual/get-started/install-and-activate-olares.md @@ -0,0 +1,20 @@ +--- +search: false +--- +## Install and activate Olares +:::warning Same network required +To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network. +::: + +1. Open LarePass, on your account activation page, tap **Discover nearby Olares**. LarePass will list the detected Olares instances in the same network. +2. Select the target Olares device from the list and tap **Install now**. +3. When the installation completes, tap **Activate now**. Olares will enter the activation process, including initial configuration and network setup. +4. Follow the on-screen instructions to reset the login password for Olares, then tap **Complete**. + +![Activate Olares via LarePass](/images/manual/get-started/activate-olares-mdns.png#bordered) + +Once activation is complete, LarePass will display the desktop address of your Olares device, such as `https://desktop.marvin123.olares.com`. + +![Access Olares via browser](/images/manual/get-started/access-olares-via-browser.png#bordered){width=30%} + + \ No newline at end of file diff --git a/docs/manual/get-started/install-olares-linux.md b/docs/manual/get-started/install-olares-linux.md new file mode 100644 index 000000000..d2544f5ec --- /dev/null +++ b/docs/manual/get-started/install-olares-linux.md @@ -0,0 +1,32 @@ +--- +description: Detailed instructions for installing Olares on Linux systems including Ubuntu and Debian. Covers system requirements, installation steps, and activation process. +--- +# Install Olares on Linux via the script +This guide explains how to install Olares on Linux using the provided installation script. + +## System requirements + +Make sure your device meets the following requirements. + +- CPU: At least 4 cores +- RAM: At least 8GB of available memory +- Storage: At least 64GB of available space (SSD recommended) +- Supported systems: + - Ubuntu 24.04 LTS or later + - Debian 11 or later + +:::info Version compatibility +While these specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). +::: + +## Install Olares + +In your terminal, run the following command: + + + + + + + + \ No newline at end of file diff --git a/docs/manual/get-started/install-olares.md b/docs/manual/get-started/install-olares.md new file mode 100644 index 000000000..2b2a012e7 --- /dev/null +++ b/docs/manual/get-started/install-olares.md @@ -0,0 +1,47 @@ +--- +description: Get started with Olares on Linux using the one-line script +--- +:::warning Note for Mainland China users +The steps in this guide differ for users in Mainland China due to regional differences. For a version tailored to your region, please read the Simplified Chinese documentation. +::: + +# Install Olares on Linux + +This document introduces how to install and activate Olares on Linux. **Linux** (Ubuntu or Debian) is the recommended platform for running Olares, as it offers the best performance and stability in production environments. + +Before installing, make sure to [create an Olares ID](create-olares-id.md) and verify that your operating system and hardware meet the minimum requirements. + +:::info Having trouble with installation? +If you encounter issues during the installation process, feel free to [submit a GitHub Issue](https://github.com/beclab/Olares/issues/new). Please include the following information when submitting: + +- The platform or environment you're using (e.g., Ubuntu, Docker, WSL, etc.). +- The installation method (script installation or Docker image). +- Detailed error information (including logs, error messages, or screenshots). +::: + +## System requirements + +Make sure your device meets the following requirements. + +- CPU: At least 4 cores +- RAM: At least 8GB of available memory +- Storage: At least 64GB of available space (SSD recommended) +- Supported systems: + - Ubuntu 20.04 LTS or later + - Debian 11 or later + +:::info Version compatibility +While these specific versions are confirmed to work, the process may still work on other versions. Adjustments may be necessary depending on your environment. If you meet any issues with these platforms, feel free to raise an issue on [GitHub](https://github.com/beclab/Olares/issues/new). +::: + +## Install Olares + +In your terminal, run the following command: + + + + + + + + diff --git a/docs/manual/get-started/installation-troubleshooting.md b/docs/manual/get-started/installation-troubleshooting.md new file mode 100644 index 000000000..ae68503af --- /dev/null +++ b/docs/manual/get-started/installation-troubleshooting.md @@ -0,0 +1,9 @@ +--- +search:false +--- +:::info Troubleshooting installation issues +If any issues arise during installation, report them by [creating a GitHub issue](https://github.com/beclab/Olares/issues/new). Include the following details: +- The platform or environment being used (e.g., Ubuntu, Docker, WSL, etc.). +- The installation method (script or Docker image). +- Detailed error information (including logs, error messages, or screenshots). +::: \ No newline at end of file diff --git a/docs/manual/get-started/log-in-to-olares.md b/docs/manual/get-started/log-in-to-olares.md new file mode 100644 index 000000000..9b0297592 --- /dev/null +++ b/docs/manual/get-started/log-in-to-olares.md @@ -0,0 +1,17 @@ +--- +search: false +--- +## Log in to Olares + +1. Enter the Olares desktop address in your browser, and press any key to continue. +2. On the login page, enter your Olares login password. + + ![Log in](/images/manual/get-started/log-in.png#bordered) +3. You will be prompted to complete the two-factor verification. You can confirm login on LarePass, or manually enter the 6-digit verification code. + ::: info + The verification code is time-sensitive. Ensure you enter it before it expires. If it does, you will need to generate a new code. + ::: + + ![Confirm login](/images/manual/get-started/confirm-login.png#bordered) + +Once you've logged in, you'll be directed to the Olares desktop.🎉 \ No newline at end of file diff --git a/docs/manual/get-started/next-steps.md b/docs/manual/get-started/next-steps.md new file mode 100644 index 000000000..c117ac913 --- /dev/null +++ b/docs/manual/get-started/next-steps.md @@ -0,0 +1,129 @@ +--- +description: Guide to getting started with Olares after installation including initial setup, configuration, and essential features. +--- + + +# What's next + +You're now ready to dive into Olares's powerful features. You will find it easy to get things done in Olares. + +Here are some suggested next steps: + + +
+ + + + + + + + + + + +
+ + \ No newline at end of file diff --git a/docs/manual/get-started/reusables.md b/docs/manual/get-started/reusables.md new file mode 100644 index 000000000..9f9ccc578 --- /dev/null +++ b/docs/manual/get-started/reusables.md @@ -0,0 +1,50 @@ +--- +search: false +--- + +```bash +curl -fsSL https://olares.sh | bash - +``` + +:::tip Root user password +During the installation, you may be prompted to enter your root password. +::: + +:::info Errors during installation? +If an error occurs during installation, use the following command to uninstall first: + +```bash +olares-cli uninstall --all +``` + +After uninstalling, retry the installation by running the original installation command. +::: + +## Prepare Wizard URL + +At the end of the installation process, you will be prompted to enter your domain name and Olares ID. + +![Enter domain name and Olares ID](/images/manual/get-started/enter-olares-id.png) + +For example, if your full Olares ID is `alice123@olares.com`: + +- **Domain name**: Press `Enter` to use the default domain name or type `olares.com`. +- **Olares ID**: Enter the prefix of your Olares ID. In this example, enter `alice123`. + +Upon completion of the installation, the initial system information, including the Wizard URL and the initial login password, will appear on the screen. You will need them later in the activation stage. + +![Wizard URL](/images/manual/get-started/wizard-url-and-login-password.png) + +## Next step: Protect your Olares ID + +You're almost ready to start using Olares! Before diving in, it's crucial to ensure your Olares ID is securely backed up. Without this step, you won't be able to recover Olares ID if needed. + +- [Back up your mnemonic phrase](/manual/larepass/back-up-mnemonics.md) + +:::info Having trouble with installation? +If you encounter issues during the installation process, feel free to [submit a GitHub Issue](https://github.com/beclab/Olares/issues/new). Please include the following information when submitting: + +- The platform or environment you're using (e.g., Ubuntu, Docker, WSL, etc.). +- The installation method (script installation or Docker image). +- Detailed error information (including logs, error messages, or screenshots). + ::: diff --git a/docs/manual/glossary.md b/docs/manual/glossary.md new file mode 100644 index 000000000..7278230ec --- /dev/null +++ b/docs/manual/glossary.md @@ -0,0 +1,39 @@ +--- +description: Technical glossary of Olares, providing standard definitions and explanations for common technical concepts. Alphabetically organized for easy reference of professional terminology. +--- +# Glossary +
+ C + | + D + | + F + | + T + | + V +
+ +## C +### CNAME Record +A CNAME (Canonical Name) record is a type of DNS (Domain Name System) record that maps your custom domain name to an Olares-provided address, enabling domain-to-application mapping. + +## D +### DID +A Decentralized Identifier (DID) is a unique digital identification method that enables any person or entity to have a persistent, unique identity on the network. This identifier is fully independent and doesn't require verification or registration through a central authority. A DID is a unique string that starts with "did" and follows specific formatting and naming conventions. + +## F +### FRP +Fast Reverse Proxy (FRP) is a high-performance reverse proxy application designed for internal network penetration scenarios. It enables servers behind NAT or firewalls to provide services externally, even without public IP addresses. FRP helps users easily expose internal services to the public network. + +## T +### TOTP +Time-Based One-Time Password (TOTP) is a time-based algorithm for generating one-time passwords, widely used in two-factor authentication (2FA). It generates single-use passwords using a shared key and current time to enhance account security. Each password is valid for a brief period (typically 30 or 60 seconds) before a new one is generated. + +## V +### VC +Verifiable Credential (VC) is a digital format proof that verifies certain attributes or qualifications of its holder without revealing additional personal information. It involves three primary roles: + +* Holder: The individual who possesses and uses the credential to prove certain information +* Issuer: The authority or entity that creates and issues verifiable credentials +* Verifier: The individual or organization that needs to verify the authenticity of the holder's information by validating the credential diff --git a/docs/manual/help/faqs.md b/docs/manual/help/faqs.md new file mode 100644 index 000000000..93c92a748 --- /dev/null +++ b/docs/manual/help/faqs.md @@ -0,0 +1,105 @@ +--- +description: Find answers to common questions about Olares. +--- +# FAQs + +## What license is Olares using? + +Olares consists of a series of projects using a hierarchical authorization approach. The basic principles are: + +- Projects running on blockchain use Apache 2.0, such as [Snowinning Protocol](https://github.com/beclab/terminusdid-contract-system). +- Projects related to protocols use Apache 2.0, such as [r4](https://github.com/beclab/r4). +- Projects around Olares and LarePass use the [Olares License](https://github.com/beclab/Olares/blob/main/LICENSE.md). +- For third-party applications running on Olares, it is up to the developer to decide whether they want them open source or not and choose the license accordingly. + +For more details, visit our projects on [GitHub](https://github.com/beclab). + +## Is the Olares License an open source license? + +Olares's choice of license for its major projects is inspired by [fair code](https://faircode.io/). The [Olares License](https://github.com/beclab/Olares/blob/main/LICENSE.md) also follows these principles: + +> - Is generally free to use and can be distributed by anybody +> - Has its source code openly available +> - Can be extended by anybody in public and private communities +> - Is commercially restricted by its authors + +## Why can't I restore my account if the mnemonics goes missing? + +From 1Password’s MasterKey to crypto wallet’s mnemonic phrase, for more than ten years, the problem of mnemonic storage has not been well solved. + +The mnemonic phrase of Olares will be encrypted and stored on all devices that install LarePass. Generally, you only lose the mnemonic phrase if you lose all the devices with LarePass installed at the same time. + +Safety is the most important principle in designing our system. We will continue to improve it in the future to provide you with a better solution that balances convenience and safety. + +## Is there a difference between Olares and the current operating systems running on NAS? + +At the inception of Olares (formerly Terminus), the market already had excellent NAS operating systems such as [Synology](https://www.synology.com/en-global/dsm/packages), [CasaOS](https://github.com/IceWhaleTech/CasaOS), and [Umbrel](https://github.com/getumbrel/umbrel). They have indeed inspired us. + +But we do think the operating system running on Edge should be able to: + +- Orchestrate resources for multiple hardware +- Manage applications in sandboxes + +This is difficult to achieve with the above-mentioned NAS operating systems built on Docker Compose. + +Meanwhile, Olares aims to provide a one-stop self-hosted solution, which goes beyond the scope of general NAS operating systems. + +## Do I need to pay for Olares? + +When you're self-hosting, you can essentially use Olares for free. + +But for the following two features, we may introduce reasonable charges due to the cost (currently both are provided for free): + +- **Backup** + + We provide 10G of free backup space for each Olares ID on Olares Space. When the archive size exceeds this limit, we will charge you a certain fee to cover the cloud provider fee. + +- **Fast Reverse Proxy (FRP)** + + Accessing Olares locally or via VPN is essentially free. However, if you’re providing external services like hosting a blog, traffic will be forwarded to a Fast Reverse Proxy (FRP) server before reaching Olares. In this case: + + - If you use your own FRP service, Olares does not impose any charges. + - If you opt to use the default FRP service from Olares, we offer a free monthly traffic allowance of 2GB. This is usually sufficient for users who do not provide external services through Olares. Additional charges may apply if your usage exceeds this limit. + +## When are other languages available? + +Right now we only support English and Simplified Chinese. + +In fact, we have completed i18n replacement in all front-end projects. However, we lack the experience in maintaining translation resources for a fast iterating project through the open source community. We are still learning. + +## What are the differences among the different "passwords"? + +Olares does have various passwords to ensure its security, including: + +- Private key +- The password of LarePass: + - On mobile phones, biometrics can be used for login + - On computers and browser plug-ins, manual input is required +- Password for first activation of Olares +- Password for Olares login +- Second verification code when logging in to Olares + +Don't panic! For daily use, what you need to enter is the two-step verification code when logging in to Olares. + +## How to deploy multi-user applications? + +It depends on whether you want to provide external service or simply let internal Olares users use it. + +- To provide services to the public, you can select the Entrance to access the application as **Public**. This allows the application to manage its own user registration and authentication. +- To provide internal access only, you can deploy the Cluster-scoped version of such products on Olares. + +For Gitlab, we provide two versions of porting: [Gitlab Pure](https://github.com/beclab/apps/tree/main/gitlabpure) and [Gitlab Fusion](https://github.com/RLovelett/gitlab-fusion). + +## How can I reactivate Olares with the same Olares ID? + +If you've reinstalled Olares, the Olares instance you originally activated will no longer be accessible. To reactivate Olares using the same Olares ID: + +::: tip Install with the same Olares ID +During the Olares installation, ensure that you have entered the exact same domain and Olares ID that you used previously. +::: + +![Reactivate](/images/manual/help/reactivate.png) + + 1. Open LarePass on your phone and enter your previous account. You should see a red prompt on the top saying "No active Olares found". + 2. Tap **Learn more** > **Reactivate** to enter the QR scan screen. + 3. Tap **Scan QR code** to scan the QR code on the wizard page and activate Olares. diff --git a/docs/manual/help/index.md b/docs/manual/help/index.md new file mode 100644 index 000000000..69a1cef2b --- /dev/null +++ b/docs/manual/help/index.md @@ -0,0 +1,3 @@ +# Help and support + +Text diff --git a/docs/manual/help/request-technical-support.md b/docs/manual/help/request-technical-support.md new file mode 100644 index 000000000..5c01902e9 --- /dev/null +++ b/docs/manual/help/request-technical-support.md @@ -0,0 +1,21 @@ +--- +description: Learn how to get technical support for Olares through GitHub discussions and issues. Guide includes steps to collect and export system logs for troubleshooting. +--- +# Request technical support + +If you need help with Olares, you can reach out to Olares team through GitHub. + +If you have an Olares device running, you can use a convenient one-click solution to collect and export logs for troubleshooting purpose. This will help Olares team assist you more effectively. + +## Request support + +1. Visit the [Olares GitHub Repository](https://github.com/beclab/Olares) and choose one of the following options: + - Open a new **[Discussion](https://github.com/beclab/Olares/discussions/new?category=q-a)** thread (for general questions or assistance). + - Create a new **[Issue](https://github.com/beclab/Olares/issues/new)** (for bug reports or technical problems). +2. Provide a brief description of the issue or question to help the Olares team assist you more effectively. Include the following information if possible: + - Steps to reproduce the issue. + - Any error messages or unexpected behaviors. + - Details about your environment (e.g., operating system, Olares version). + +It's recommended to attach the Olares system log. For detailed instructions, see [Export system log](../olares/settings/developer.md#export-system-logs). + diff --git a/docs/manual/help/troubleshooting-guide.md b/docs/manual/help/troubleshooting-guide.md new file mode 100644 index 000000000..1a10f3781 --- /dev/null +++ b/docs/manual/help/troubleshooting-guide.md @@ -0,0 +1,3 @@ +# Troubleshooting guide + +Text diff --git a/docs/manual/larepass/activate-olares.md b/docs/manual/larepass/activate-olares.md new file mode 100644 index 000000000..5824ac460 --- /dev/null +++ b/docs/manual/larepass/activate-olares.md @@ -0,0 +1,60 @@ +--- +title: Activate and log in to Olares +description: Learn how to activate Olares for the first time, reactivate it after reinstallation, and complete secure two-factor login using the LarePass mobile app. +--- + +# Activate Olares + +Olares uses your **Olares ID** and the **LarePass mobile app** to provide a secure and seamless authentication experience. This document guides you on how to activate Olares and complete two-factor verification during login using LarePass. + +:::warning Same network required for admin users +To avoid activation failures, ensure that both your phone and the Olares device are connected to the same network. +::: + +## Activate Olares for the first time + +After [completing the installation](../get-started/install-olares.md#install-olares) and initial setup in the wizard, you can activate your Olares instance using your Olares ID through the **LarePass** app. + +::: tip Note +New members can activate their account through the wizard without installing Olares locally. See [Create a new member](../olares/settings/manage-team.md#create-a-new-member) for more information. +::: + + +![2FA](/images/manual/larepass/activate-olares.png#bordered) + +1. Open LarePass app. +2. Tap **Scan QR code** to scan the QR code on the Wizard page. +3. Follow the on-screen instructions on LarePass to reset the login password for Olares. + +After successful activation, the LarePass app will automatically return to the home screen, and the Wizard will redirect you to the login page. + +## Reactivate Olares with the same Olares ID + +If you have reinstalled Olares, the original instance becomes unavailable. You can reactivate the new installation using your existing Olares ID: + +1. Open LarePass on your phone. You can see a red prompt: "No active Olares found". +2. Tap **Learn more** > **Reactivate** to enter the QR scan page. +3. Tap **Scan QR code** to scan the QR code on the wizard page and activate Olares. + +## Two-factor verification with LarePass + +When you log in to Olares, you will be promoted to complete the two-factor verification. You can either confirm the login directly in LarePass app or manually enter a 6-digit verification code. + +- **To confirm login on LarePass**: + ![2FA](/images/manual/larepass/second-confirmation.png#bordered) + 1. Open the login notification on your phone. + 2. In the message, click **Confirm** to complete the login process. + +- **To manually enter the verification code**: + ![OTP](/images/manual/larepass/otp-larepass.jpg#bordered) + + 1. On the Wizard page, select **Verify using one time password from LarePass**. + 2. Open LarePass on your phone and go to **Settings**. + 3. Tap the authenticator on the top to generate the one time verification code. + 4. Return to your Wizard page and enter the cod e to complete the login. + +::: tip Note +The verification code is time-sensitive. Ensure you enter it before it expires. If it does, you will need to generate a new code. +::: + +After successful verification, you'll be redirected to the Olares desktop. diff --git a/docs/manual/larepass/autofill.md b/docs/manual/larepass/autofill.md new file mode 100644 index 000000000..601b6a6a2 --- /dev/null +++ b/docs/manual/larepass/autofill.md @@ -0,0 +1,80 @@ +--- +description: Configure and use LarePass autofill features to securely manage passwords across devices, automatically save credentials, and streamline your login experience. +--- +# Autofill passwords with LarePass + +Password autofill eliminates the hassle of manually typing credentials while maintaining security. With LarePass, you can securely store passwords in your Vault and automatically fill them across your devices. + +## Before you begin + +Make sure you have LarePass mobile clients or Chrome extension installed on your device, and logged in using your Olares ID. + +:::tip +For different download options of LarePass, visit the [official website](https://olares.com/larepass). +::: + +## Enable autofill service + + + + + + +## Save password +When you enter credentials in an app or website, LarePass will detect this action and prompt you to save them. +:::info +On iOS, passwords cannot be automatically saved. You can manually add a vault item or use the Chrome extension. Vault items sync across all platforms. +::: +1. Log in to an app or website. +2. When prompted, click **Save** to store your password in LarePass. +3. In the details page or window, enter a name for this vault item, and click **Save**. + +## Use autofill + + + + + + + + + diff --git a/docs/manual/larepass/back-up-mnemonics.md b/docs/manual/larepass/back-up-mnemonics.md new file mode 100644 index 000000000..349859a9a --- /dev/null +++ b/docs/manual/larepass/back-up-mnemonics.md @@ -0,0 +1,55 @@ +--- +outline: [2, 3] +description: Learn how to securely back up your Olares ID mnemonic phrase for account recovery and protection. +--- + +# Back up mnemonic phrase +A mnemonic phrase is a sequence of 12 words that serves as the sole method to recover your Olares ID. If you lose your devices or need to import your Olares account, you can use the phrase to regain your access to Olares. + +:::warning +In a decentralized system, you are responsible for your own security. + +Keep your mnemonic phrase safe and secret, and never share it with anyone. It is the only way to recover your Olares account. +::: +## Set up local password +When exporting or backing up your mnemonic phrase for the first time, you may be prompted to set a local password for LarePass. This password is only used to unlock LarePass services on the current device. + +After setting up, you can choose to enable biometric unlock for more secure and convenient access using face recognition or fingerprint. + +![Set up local password](/images/manual/get-started/set-up-local-password.png) + +:::info +* All Olares IDs on the same device share one local password in the LarePass app. +* Local passwords for LarePass apps installed on different devices are independent and stored separately. +::: + +## Reveal and back up your mnemonic phrase +1. Open the LarePass app, and go to **Settings** > **Account** page. +2. Click **Backup now**. +3. Read the risk warning about losing your mnemonic phrase and click **Start**. +4. Click to view the 12-word mnemonic phrase, and enter your local password for identity verification. +5. Securely record the mnemonic phrase and store it in a safe place. +6. Click **Next**. + :::warning + While clicking **Copy** will save the mnemonic phrase to your clipboard, this poses a security risk. For maximum security, we strongly recommend backing up your mnemonic phrase offline. + ::: +7. Verify your backup by arranging the mnemonic phrase in the correct order. +8. Click **Completed**. + If arranged correctly, you have successfully backed up your mnemonic phrase. + + ![Back up mnemonic phrase](/images/manual/get-started/backup-mnemonic-phrase.png) + +## FAQs +### What happens if I lose my mnemonic phrase? +Losing your mnemonic phrase will result in serious consequences: + +* You will lose ownership of your digital identity (DID) and Olares ID. +* You won't be able to access data stored in Vault. + +To prevent this, we strongly recommend taking these precautions: + +* **Offline backup**: Write down the 12-word mnemonic phrase and store it securely, such as in a safe. +* **Multi-device backup**: Use LarePass's Vault to encrypt and save your mnemonic phrase on multiple devices. You only risk losing your mnemonic phrase if all these devices are lost. + +### I've activated Olares, why do I get a password error when trying to view my mnemonic phrase in LarePass? +If you encounter a password error, it may be because you haven't set a local password. Open the LarePass app, go to **Settings** > **Security**, and set a local password. Then try the backup process again. diff --git a/docs/manual/larepass/create-account.md b/docs/manual/larepass/create-account.md new file mode 100644 index 000000000..daecaf9da --- /dev/null +++ b/docs/manual/larepass/create-account.md @@ -0,0 +1,77 @@ +--- +outline: [2, 4] +--- + +# Create and manage accounts + +Managing Olares accounts is a core function of LarePass. If you are new to Olares, you will need to start by creating an Olares ID. This guide walks you through the process, and other commonly used account operations as well. + +::: tip Note +Olares ID creation is only available on LarePass mobile. +::: + +## Create an Olares ID + +Before you start, ensure you have downloaded the [LarePass](https://olares.com/larepass) app on your phone. Depending on your personal preference, you can use one of the following options to create your Olares ID: + +- **Quick creation**: Create an Olares ID by entering an available name that meets the requirements. This is the default mode. +- **Advanced creation**: Link an existing trusted identity (such as social accounts) with Olares ID using Verification Credentials (VC). This is for individual or organizational users who require enhanced security and more distinctive IDs or domains. + +### Quick creation + +To create an individual Olares ID quickly: + +1. In LarePass app, tap **Create an account**. + +2. Enter your desired Olares ID. It must be at least 8 characters long and contain only lowercase letters and numbers. +3. Click **Continue** to finish the creation process. + + ![Fast creation](/images/manual/larepass/create-olares-id.png) + +After you get your Olares ID, wait for [Olares installation](../get-started/install-olares.md) to complete, then proceed with [activation](../get-started/activate-olares.md). + +### Advanced creation + +::: tip VC support +Olares currently supports VC via Google Gmail. For details, refer to the [Gmail Issuer Service](/developer/contribute/olares-id/verifiable-credential/olares.md#gmail-issuer-service). +::: + + + + + + +## Import an existing account + +You can also set up an account by importing an existing Olares ID: + +:::tip Back up mnemonic phrase +You must have already [backed up the mnemonic phrase](back-up-mnemonics.md) for the Olares ID to import. +::: + +1. In LarePass app, tap **Import an account**. +2. Enter the 12-word mnemonic phrase to import your Olares ID. diff --git a/docs/manual/larepass/index.md b/docs/manual/larepass/index.md new file mode 100644 index 000000000..aabc663da --- /dev/null +++ b/docs/manual/larepass/index.md @@ -0,0 +1,79 @@ +--- +outline: [2, 3] +--- + +# LarePass documentation + +LarePass is the official cross-platform client software for Olares. It acts as a secure bridge between users and their Olares systems, enabling seamless access, identity management, file synchronization, and secure data workflows across all your devices, whether you're on mobile, desktop, or browser. + +![LarePass](/images/manual/larepass/larepass.png) + + +## Key features + +### Account & identity management +Create and manage your Olares ID, connect integrations with other services, and back up your credentials securely. +- [Create an Olares ID](create-account.md) +- [Back up mnemonics](back-up-mnemonics.md) +- [Set or reset local password](back-up-mnemonics.md#set-up-local-password) +- [Manage integrations](integrations.md) + +### Secure file access & sync +Access and sync your Olares files across devices. +- [Manage files with LarePass](manage-files.md) +- [Sync and share files](sync-share.md) + +### Device & network management +Activate and manage Olares devices, and securely connect to Olares via LarePass VPN. +- [Activate your Olares device](activate-olares.md) +- [Log in to Olares with 2FA](activate-olares.md#two-factor-verification-with-larepass) +- [Manage Olares](manage-olares.md) +- [Switch networks](manage-olares.md#switch-from-wired-to-wireless-network) +- [Enable VPN for remote access](private-network.md) + +### Password & secret management +Use Vault to autofill credentials, store passwords, and generate 2FA codes across devices. +- [Autofill passwords](/manual/larepass/autofill.md) +- [Generate 2FA codes](/manual/larepass/two-factor-verification.md) + +### Knowledge collection +Use LarePass to collect web content and follow RSS feeds. +- [Collect content via LarePass extension](manage-knowledge.md#collect-content-via-the-larepass-extension) +- [Subscribe to RSS feeds](manage-knowledge.md#subscribe-to-rss-feeds) + +--- + +## Download and install LarePass + +Get the latest version for your device at the [LarePass website](https://www.olares.com/larepass). + +### Install the LarePass browser extension + + + + + + + + :::tip Quick access + After installation, pin the LarePass extension from Chrome’s extension menu for one-click access. + ::: diff --git a/docs/manual/larepass/integrations.md b/docs/manual/larepass/integrations.md new file mode 100644 index 000000000..7ab0dfa7e --- /dev/null +++ b/docs/manual/larepass/integrations.md @@ -0,0 +1,85 @@ +--- +outline: [2, 3] +description: Connect Olares with third-party services to enhance functionality. Learn how to integrate, authorize, and manage connected services for seamless data synchronization. +--- + +# Manage integrations in LarePass + +LarePass is your central hub for connecting Olares with third-party services like Google Drive, Dropbox, AWS S3, and Tencent COS. These integrations extend the capabilities of your Olares environment like file sync, secure backup, and more. + +:::info +We're working on adding support for more third-party integrations that will connect you with more external services to your Olares account. +::: + +## Connect to Olares Space + +Olares Space is a cloud hosting service for Olares that shares the same account system with LarePass and Olares. + +### Step 1. Log in to Olares Space + +1. Open https://space.olares.com/login in your browser. +2. Open LarePass on your mobile device. +3. On the Settings page, tap the "Scan" icon in the top-right corner. +4. Scan the QR code on the Olares Space login page. +5. Confirm the risk prompt and proceed with the login. + +### Step 2. Authorize Olares Space + +1. In the LarePass app, go to **Settings** > **Integration**. +2. Tap add in the top-right corner and select **Space** to add your Olares Space account. + +### Step 3. Associate Olares ID +Associating your Olares ID allows you to import a blockchain wallet, which is necessary for using NFT images as unique avatars in your profile. + +1. Open the Settings app from the Dock or Launchpad. +2. Select **Integration** from the left sidebar. +3. Click on the Olares Space card on the right to view details. +4. Click **Bind**. This will trigger a confirmation prompt in LarePass app. +5. Open the LarePass app. You should see a confirmation prompt. If not: + + a. Go to **Settings** > **Integration**. + + b. Tap the Olares Space card. + + c. In the confirmation prompt, tap **Confirm** to authorize. +6. Return to Olares, and click **Confirm** to complete the association to your Olares ID. + +## Add a cloud drive via OAuth + +OAuth-based integrations like Google Drive and Dropbox require initial setup via the LarePass mobile app: + +1. Open LarePass on your mobile device. + +2. Tap **Settings** > **Integration**, then tap add in the top-right corner. + +3. Select either Google Drive or Dropbox. + +4. Follow the login prompts to authorize your account. + +Once authorized, you'll see the connected account in the integration list. You can now access the storage in Files. + +## Add a cloud storage using API-keys + +Services like AWS S3 and Tencent Cloud COS require setup using API keys (Access Key & Secret Key). You can do this directly from the LarePass app or from the **Integration** settings within Olares: + +1. Open LarePass on your mobile device. +2. Tap **Settings** > **Integration**, then tap add in the top-right corner. +3. Select AWS S3 or Tencent COS. +4. Enter your Access Key, Secret Key, and other required credentials, then tap **Confirm**. + +Once configured, you'll see the connected service in the integration list. And you can access the cloud storage through Files. + +Alternatively, you can configure these integrations directly within [Olares Settings](/manual/olares/settings/integrations.md). + + +## Disconnect integrations +::: warning +Disconnecting Olares Space may affect your ability to manage devices, and access cloud backups through the Olares Space interface. +You can always reconnect later if needed. +::: + +To disconnect an integration from LarePass: + +1. Open LarePass app, and go to **Settings** > **Integration**. +2. Tap on the integration you wish to remove. +3. Tap more_horiz in the top-right corner, and tap **Delete**. diff --git a/docs/manual/larepass/manage-files.md b/docs/manual/larepass/manage-files.md new file mode 100644 index 000000000..697d60585 --- /dev/null +++ b/docs/manual/larepass/manage-files.md @@ -0,0 +1,93 @@ +--- +description: Learn essential file operations in Larepass including adding new files, editing existing content, and downloading files across different devices. +--- +# Common file operations on LarePass + +File management operations in LarePass offers consistent experience as the Files app, with slight differences on different platforms. This document gets you started with some common file tasks in LarePass. + +## Upload files + +Files uploaded via LarePass will automatically sync to your Olares of the same account. + +### Upload via LarePass desktop + +:::info Import your Olares ID +To start using LarePass desktop, you must import your Olares ID by pasting your mnemonics. Make sure you have [backed up your mnemonics](back-up-mnemonics.md). +::: +LarePass desktop offers the same upload experience as the Files app, with automatic syncing to your Olares. + +### Upload via LarePass mobile +You can also upload files or folders on your phone via the LarePass app. + + + + + + +## Download files + +When downloading multiple files via LarePass to your local, the tasks are queued, allowing you to pause, resume, or cancel tasks, and easily locate downloaded files. +:::tip +For large files or multiple downloads, it's recommended to use the LarePass desktop application for more powerful download management and a better user experience. +::: + + + + + + +## Delete files +:::warning +Deleted files cannot be recovered. +::: + + + + + diff --git a/docs/manual/larepass/manage-knowledge.md b/docs/manual/larepass/manage-knowledge.md new file mode 100644 index 000000000..7dbb75e37 --- /dev/null +++ b/docs/manual/larepass/manage-knowledge.md @@ -0,0 +1,83 @@ +--- +title: Manage Knowledge with LarePass +description: Use LarePass to collect web content, videos, and RSS feeds across devices. +--- + +# Manage knowledge with LarePass + +LarePass lets you capture and manage knowledge from across the web, whether it's articles, podcasts, videos, or RSS feeds. With the browser extension and mobile app, you can collect content in just a few clicks and sync it seamlessly with **Wise**, the knowledge management app in Olares. + +This guide walks you through how to collect content using the **LarePass extension** and **mobile client**, and how to subscribe to RSS feeds for continuous content updates. + +Learn more about organizing and using your content in the [Wise guide](../olares/wise/). + +## Before you start + +Before collecting web content, ensure the following: + +- Your Olares device is running. +- You have installed LarePass on your phone. +- You have [installed the LarePass browser extension](index.md#install-the-larepass-browser-extension) for your Chrome. + + +## Collect content via the LarePass extension + +The LarePass browser extension is the core tool for content discovery and collection. + +::: tip Upload Cookies for a Better Experience +Some websites restrict access for anonymous users. In these cases, you can upload your browser cookies to Olares to improve content capture. + +1. Log in to the website and open the **LarePass extension**. +2. Go to **Collect** > **Cookie**, then click **Upload**. +3. You can hover over each cookie to view details. To exclude a cookie, click **X** to remove it from the selection. +::: + +To collect web content using the extension: + +1. Navigate to the content page (e.g. a CNN article). +2. Open the **LarePass extension**. It will automatically detect collectable content. +3. In **Collect** > **Page**, click add_box next to the title to add the page to Wise. + + ![Collect web content](/images/manual/tutorials/wise-collect-web-content.png#bordered) + +Collected content will appear in **Library** > **Articles** in **Wise**. Associated media files (images, videos, audio) will also be saved locally to `/download/Wise/Article`. + + +## Collect content via the LarePass app + +You can also share content from your mobile browser directly to LarePass. + +:::info +Steps may vary depending on your device and browser. The following example uses **Safari on iOS**. +::: + +1. Tap the **ios_share Share** button in the browser. + - Choose **LarePass** from the share menu, or + - Tap **Other Actions** and select **LarePass**. + + ![Share to Wise](/images/manual/tutorials/wise-add-articles-via-share.png#bordered) + +2. You’ll be redirected to the LarePass app, which will auto-detect the collectable content and prompt you to add it to Wise. +3. Tap **Confirm** to add the content. + +::: tip Tip: Copy URL to Share +Alternatively, you can copy a URL and open LarePass directly. It will detect the URL in your clipboard and the associated content automatically. +::: + +Once added, the content will appear in **Library** > **Articles** in Wise. + + +## Subscribe to RSS feeds + +LarePass also supports RSS subscriptions, allowing you to follow podcasts, blogs, and content sources effortlessly. + +To subscribe via the extension: + +1. Visit the RSS feed or podcast page (e.g. `https://www.spreaker.com/podcast/paranormal-mysteries--2321086`). +2. Open the **LarePass extension**. It will auto-detect the RSS source and show the **RSS** tab. +3. Click bookmark_add next to the desired feed to subscribe. + + ![Subscribe to podcast](/images/manual/tutorials/wise-sub-podcast.png#bordered) + +Subscribed feeds will be synced to **Wise**, so you can access all new content from one centralized place. + diff --git a/docs/manual/larepass/manage-olares.md b/docs/manual/larepass/manage-olares.md new file mode 100644 index 000000000..5d2829cfd --- /dev/null +++ b/docs/manual/larepass/manage-olares.md @@ -0,0 +1,94 @@ +# Manage Olares with LarePass + +The LarePass app allows you to easily manage your Olares device. You can monitor system status, manage network connections, perform remote controls, and access key device information from your phone. + +This guide walks you through the core management features available in LarePass. + +## Prerequisites + +Before you begin, ensure the following: + +- You have a valid Olares ID and an activated Olares device. +- Your Olares device is powered on and connected to a network. +- Your phone and Olares device are on the same local network. +- Your current account has administrator permissions. + +## Access Olares management + +To access the Olares management page: + +1. Open LarePass app, and go to **Settings**. +2. Tap your Olares ID to enter the Olares management interface. + +## Remote device control + +In the upper-right corner of the Olares management page, tap the power_settings_new icon to access remote control options: + + ![Device control](/images/manual/larepass/device-control.png) + +- **Restart device** – Reboots the device. Status will show `Restarting`... and revert to `Olares Running` after approximately 5–8 minutes. +- **Remote shutdown** – Powers off the device. Status will display `Powered off`. You must turn it on manually afterward. + +## Configure network + +Tap **Wi-Fi configuration** to view or modify the current network settings of your Olares device. + +### Switch from wired to wireless network + +If Olares was activated over Ethernet, you can switch to the Wi-Fi on the same network: + +![Wi-Fi switch](/images/manual/larepass/switch-wifi.jpg) + +1. Tap the **Wi-Fi configuration** option to enter the network selection page. +2. Tap the Wi-Fi network from the list. If the network is password-protected, enter the password and tap **Confirm**. +3. Once connected, the network switches to Wi-Fi automatically. The transition takes approximately 5 minutes. The Olares status will change to `IP changing` before it reverts to `Olares Running`. + +You can switch back to the wired network following the same steps. + +::: tip Wired network recommended +To ensure an optimal and stable connection, we recommend using a wired network whenever possible. +::: + +### Update IP address + +If your Olares device moves to a different network: + +1. Connect the Olares device to your wired network via Ethernet and power it on. Ensure your phone is connected to the Wi-Fi for that same network. +2. Open LarePass on your phone and go to the **Olares management** page. +3. LarePass will automatically scan Olares device within the network. When found, Olares will appear as `IP changing` in LarePass. +4. Once IP update finishes, the status will revert to `Olares running`. This process may take 5–10 minutes. + +### Set Wi-Fi via Bluetooth + +If you can't connect your Olares to a wired network during activation, or if Olares is on a different wired network than your phone, LarePass won't be able to find it. This can prevent you from completing activation or device management. In such cases, use the **Bluetooth network configuration** feature to connect your Olares to your phone's Wi-Fi network. + ![Bluetooth network](/images/manual/larepass/bluetooth-network.png) + +1. On the **Olares not found** page, tap the **Bluetooth network configuration** option. LarePass will use your phone's Bluetooth to scan for the nearby Olares device that match your current Olares ID. +2. When your device is found, tap **Network configuration**. +3. From the list of wireless networks available to your Olares, tap the Wi-Fi network your phone is connected to. If it's password-protected, enter the password and tap **Confirm**. + + ::: tip Note + If you select a Wi-Fi network different from your phone's, LarePass will still be unable to recognize your Olares device after it connects. + ::: + +4. Olares will begin the network switching process. You'll see a success message when it's complete. If you return to the Bluetooth network setup page, you'll see that Olares' IP address has changed to your phone's Wi-Fi subnet. + ::: tip Note + The process takes longer if your Olares was activated earlier as the network switch affects more services. + ::: +5. Go back to the device scan page, and you will now be able to discover your Olares device. You can now proceed with [device activation](activate-olares.md) or device management as instructed in this document. + +## Uninstall Olares + +This will reset your device to the prepared installation phase, where you can scan the LAN to re-install and activate Olares. + +![Uninstall Olares](/images/manual/larepass/restore-to-factory.png) + +::: warning Proceed with caution +This will permanently delete all your accounts info and data. Proceed with caution. +::: + +1. On the **Olares management** page, tap **Restore to Factory Settings**. + +2. Review the risk prompt and enter your local LarePass lock screen password. If not set, you will be prompted to set one first. + +3. Wait for the uninstallation to complete. You will return to the Olares login screen when it's done. diff --git a/docs/manual/larepass/private-network.md b/docs/manual/larepass/private-network.md new file mode 100644 index 000000000..a7d5db734 --- /dev/null +++ b/docs/manual/larepass/private-network.md @@ -0,0 +1,81 @@ +--- +outline: [2, 3] +description: Access Olares applications securely from anywhere using LarePass VPN. Learn about VPN setup and troubleshooting in LarePass. +--- + +# Access Olares anywhere via LarePass VPN + +Enabling the LarePass VPN creates a secure, private connection to your Olares. It's the simplest and most reliable way to access your private applications and services from anywhere, guaranteeing both security and speed. + +This document walks you through how to enable LarePass VPN. + +## How access works in Olares + +In Olares, you access applications & services via their dedicated URLs (e.g., `app.yourname.olares.com`). Depending on the intended accessibility, there are two types of entrances: + +- **Public entrance**: Accessible to anyone with no authentication. For example, a blog page that you host on WordPress. Traffic is routed through Cloudflare Tunnel or FRP before reaching Olares. +- **Private entrance**: Intended only for you, such as Desktop, Vault, the management console of WordPress. There are two scenarios when accessing private entrances: + + - LarePass VPN enabled: Traffic is routed through VPN (TailScale) wherever you are. + - LarePass VPN not enabled: Traffic routing is the same way as public entrances. + +::: warning Always enable VPN for private access +For the best experience with private entrances, we strongly recommend enabling the LarePass VPN. It ensures your connection is always encrypted, direct, and fast. +::: + +::: tip Note +Starting with Olares 1.12, you no longer need a separate `.local` address (e.g., `app.local.yourname.olares.cn`) for local access to private applications. The single address (e.g., `app.yourname.olares.cn`) now automatically provides a fast, direct connection to Olares when the LarePass VPN is active. +::: + +## Enable VPN on LarePass + +:::tip +For different LarePass download options, visit [the official page](https://olares.com/larepass). +::: + +![VPN](/images/manual/larepass/vpn.jpg) + +### On LarePass mobile client +1. Open LarePass, go to **Settings** > **Account**. +2. Turn on the VPN switch. + +### On LarePass desktop client +1. Open LarePass, click on the avatar area in the top left corner of the main interface. +2. Turn on the switch for **VPN connection** in the pop-up panel. + +Devices with activated VPN will use the VPN connection to access Olares, whether through the LarePass client or a browser. + +:::info +iOS or macOS versions of LarePass will require adding a VPN configuration file to the system when turning on the VPN. Follow the prompts to complete the setup. +::: + +## Understand connection status +LarePass displays the connection status between your device and Olares, helping you understand or diagnose your current network connection. + +![Connection status](/images/manual/larepass/connection-status.jpg) + +| Status | Description | +|--------------|--------------------------------------------------| +| Internet | Connected to Olares via the public internet | +| Intranet | Connected to Olares via the local network | +| FRP | Connected to Olares via FRP | +| DERP | Connected to Olares via VPN using DERP relay | +| P2P | Connected to Olares via VPN using P2P connection | +| Offline mode | Currently offline, unable to connect to Olares | + +::: info +When accessing private entrances from an external environment through VPN, if the status shows "DERP", it indicates that the VPN cannot directly connect to Olares via P2P and must use Tailscale's relay servers. This status may affect connection quality. If you constantly encounter this situation, please contact Olares support for assistance. +::: + +## Troubleshoot connection issues +If you encounter connection problems, LarePass will display diagnostic messages to help you resolve the issue. Here are some common scenarios and how to address them: + +![Abnormal status](/images/manual/larepass/abnormal_state.png) + +| Status message | Possible cause and recommended actions | +|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| Network issue detected. Check local network settings. | **Local network issue**
1. Wait for automatic reconnection.
The system will detect network recovery
and sync data.
2. Check your local network settings if
the issue persists. | +| VPN required to connect to Olares. | **VPN not enabled**
Click the notification banner and follow
prompts to enable VPN connection. | +| Need to log in to Olares again. | **Session expired or authentication issue**
Click the notification banner and follow
prompts to log in. | +| Need to reconnect to Olares. | **Connection interrupted or timed out**
Click the notification banner and follow
prompts to log in. After re-login, Vault
data will sync and merge with the server. | +| No active Olares found. | **Temporary network issue or Olares is restarting
or shutting down**
Wait for automatic recovery. This
usually resolves shortly.
**Olares instance no longer exists**
1. Click the notification banner and follow
prompts to reactivate Olares, enable offline
mode or ignore notification.
2. Contact Olares Admin if the issue persists. | diff --git a/docs/manual/larepass/sync-share.md b/docs/manual/larepass/sync-share.md new file mode 100644 index 000000000..07c557aa8 --- /dev/null +++ b/docs/manual/larepass/sync-share.md @@ -0,0 +1,144 @@ +--- +description: Keep files synchronized across devices and share content securely with other Olares members using built-in file sharing capabilities. +--- +# Sync and share files + +Sync in Olares is similar to cloud storage services like iCloud, where you can keep your most important information up to date, and available across all your devices. Sync also makes it easy to share files with other members within an Olares server. + +**LarePass** plays a central role in sync and share. It not only keeps your Files content synchronized across devices but also facilitates collaboration through file sharing and library management. + +This page will mainly cover: +- How to sync files across devices +- How to share files with other team members + +:::info +- Currently, file sync is available on the **LarePass desktop client** for Windows and macOS. +- Library management is supported on both the **Files app** on Olares and the **LarePass desktop client**. +- **LarePass mobile app** supports shared library access, but not creation. +::: + +## Before you begin + +Make sure you have installed the LarePass desktop client from the [official website](https://olares.com/larepass), and logged in using your Olares ID. + + +## Manage your libraries + +Library is the fundamental unit for organizing, syncing, and sharing your digital content. + +### Understand roles and permissions + +:::info +The roles and permissions described here are specific to file sharing and library management within Files. These are distinct from the overall Olares user roles and system-wide permissions. +::: + +| Operation | Owner | Member | +|----------------------------|-------|--------| +| Create library | ✅ | ✅ | +| Manage library permissions | ✅ | ❌ | +| Invite other members | ✅ | ❌ | +| Share and rename library | ✅ | ❌ | +| Remove members | ✅ | ❌ | +| Delete library | ✅ | ❌ | +| Exit library | ❌ | ✅ | + + +### Create a library + +Each user is automatically provided with their own personal library as a starting point. To create a new one: + +1. Open LarePass desktop client. +2. From the left sidebar, navigate to **Files** > **Sync**, click the add_circle to open the **New library** dialog. +3. Enter a name for the Library and click **Create**. + +Alternatively, you can create a library in the **Files** app in Olares. + +### Share a library + +:::tip +To add a member in Olares, see [manage team](/manual/olares/settings/manage-team.md). +::: + +To share a library with other members in the same Olares cluster: + +1. Select a library, and click more_horiz > **Share with**. +2. In the dialog, select users from the dropdown menu, and click **Share to user**. +3. Set file permissions for each user: + - Read-only: Users can view Library contents but cannot modify them. + - Read-write: Users can add, delete, and modify Library contents. +4. Click **Close**. + + ![Share library](/images/manual/olares/share-library.png#bordered){width="50%"} + +Invited users will see the shared library in their Sync content list. To revoke sharing permissions, simply remove the user from the sharing window. + +### Exit or delete a library + +If you don't want to share a library, you could exit sharing or delete it. + +- **Exit sharing**: Any member can exit a shared Library. When an owner exits, the library will appear in their personal library list. +- **Delete**: Only the owner can delete a shared Library. + :::warning + Deleting a library is irreversible. All files in the shared library will be permanently deleted. + ::: + +1. To exit a library: + + a. Select a shared Library and click more_horiz > **Exit sharing**. + + b. Click **Confirm** in the popup dialog. +2. To delete a library: + + a. Select a shared library and click more_horiz > **Delete**. + + b. Click **Confirm** in the popup dialog. + +## Sync your library + +Once you've created a library, you can set up synchronization to keep its contents up to date across your devices. + +### Sync library files to local + +You can download and keep a copy of your library files on your local device with two-way synchronization. + +1. Open LarePass desktop client, and navigate to **Files** > **Sync** > **My Libraries**. +2. Locate the library you just created, then click more_horiz > **Sync to local**. +3. Select your local folder, and click **Confirm**. + +The library now display a sync symbol icon, indicating active two-way synchronization. Any changes made in the library will automatically sync to your local folder. + +### Sync local files to library + +Because sync is two-way, any files placed in the synced local folder will also be uploaded to your library. + +:::tip Note +If your permission to the library is read-only, you cannot sync changes from the local folder to the Library. Your newly added and modified files will be read-only, indicated by a gray disabled icon remove. +::: + +To sync an existing local folder to your library: + +1. Create or select a Library in LarePass. +2. Specify the local folder for sync. +3. Move your files into the local folder you selected. + +This lets you use your familiar local directory structure while keeping it in sync with Olares. + +### Manage sync settings + +If you need to pause or stop synchronization for a specific Library: + +1. Locate the sync library in LarePass. +2. Click more_horiz > **Unsynchronize**. + +This action won't delete your local files. It simply halts the two-way synchronization process. + +## Handle sync conflicts + +In the rare event of a sync conflict, LarePass has you covered. When multiple devices edit the same file simultaneously: + +* The first completed edit is saved to the Library. +* A backup of the conflicting version is created with a unique filename, including the editor's Olares ID and timestamp: `test.txt(SFConflict name 2024-04-17-12-12-12)`. + +## Learn more +- [Manage team](../olares/settings/manage-team.md) +- [Manage files](../olares/files/) \ No newline at end of file diff --git a/docs/manual/larepass/two-factor-verification.md b/docs/manual/larepass/two-factor-verification.md new file mode 100644 index 000000000..347c69afc --- /dev/null +++ b/docs/manual/larepass/two-factor-verification.md @@ -0,0 +1,50 @@ +--- +description: Set up and use two-factor authentication in Olares' Vault to generate secure TOTP codes for your online accounts, enhancing login security across your services. +--- +# Generate two-factor authentication codes +Two-factor authentication (2FA) requires both your password and an authentication code when signing in. These codes are generated using Time-Based One-Time Password (TOTP), which creates temporary codes that refresh automatically. Similar to Google Authenticator or Microsoft Authenticator, Vault can generate secure 2FA codes for your online accounts. + +This guide explains how to generate two-factor authentication (2FA) codes in Vault. +## Prepare your target service +1. Log in to the website where you want to enable 2FA (e.g., GitHub or OpenAI). +2. Navigate to the security settings page and enable two-factor authentication using authenticator app. + + ![Enable GitHub 2FA](/images/manual/olares/2fa-github.png#bordered) +3. Save the provided secret key or QR code for the next steps. +:::tip +If the service provides recovery codes, store them securely. They are crucial to account recovery if you lose access to Vault. +::: + +## Create an authenticator in Vault +:::tip +Visit the [official page](https://olares.com/larepass) for download options. +::: + + + + + +Once saved, your new authenticator will immediately begin generating codes. + +## Use your 2FA generator + To use it: +1. Sign in to the website with your username and password. +2. When prompted for an authentication code, open Vault to view the current 6-digit code. +3. Enter the code to complete login. diff --git a/docs/manual/olares-vs-nas.md b/docs/manual/olares-vs-nas.md new file mode 100644 index 000000000..cb4406c3c --- /dev/null +++ b/docs/manual/olares-vs-nas.md @@ -0,0 +1,100 @@ +--- +outline: [2, 3] +description: Compares Olares and general NAS, highlighting key differences in storage solutions, application ecosystem, virtual machine support, network configuration, and AI capabilities. +--- + + +# Compare Olares and NAS + +Olares is dedicated to creating a one-stop personal cloud experience. Its core functionalities and user positioning are significantly different from traditional Network Attached System (NAS). + +This document provides a detailed comparison between Olares and general NAS systems. We will highlight key differences in storage solutions, application ecosystem, virtual machine support, network configuration, and AI capabilities, using Unraid and Synology DSM as reference points. + +## Overview + +| Attribute | Olares | NAS | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| Introduction | Olares is an open-source
personal cloud operating system. | NAS systems are primarily used for network storage, allowing flexible hardware configurations to manage data and applications. | +| Positioning | Focuses on helping users deploy
and manage digital assets locally
as an alternative to public
cloud services.
It supports running powerful
open-source applications locally,
providing users with robust
cloud computing capabilities while
ensuring complete data control
and privacy. | Focuses on individuals and small businesses, solving low-cost data storage reliability issues, but has limitations in application hosting and network security. | +| Target users | Regular users without
a technical background | Geek users and small and medium business users | +| Transparency | Open-source or source available | Usually closed-source | +| Openness | No vendor lock-in | Closed ecosystem | +| Application security | Supports application sandboxing,
isolating network, storage,
and computing resources.
Permissions must be declared
and user authorization obtained
during installation. | No application sandboxing. Most third-party applications run with root privileges, and users bear the security risks themselves. | +| Network security | Provides public and private
access, using reverse proxy
and VPN to achieve service security. | Only supports external access for limited system applications by default. Custom solutions by users may pose security risks. | +| Developer friendliness | Provides development tools
with familiar technology
stacks to deploy services
and develop applications. | Does not support developer tools or application development. | +| AI | 1. Advanced GPU management (v1.12)
2. One-click installation support
for over 30 AI applications
and models
3. Supports inter-application and
model calls
4. Supports MCP (v1.12) | ❌ | + +## Project information + +| Attribute | Olares | Unraid | Synology DSM | +| ---- | ------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| Year | 2022 | 2005 | 2000 | +| Open Source | ✅ | ❌ | ❌ | +| Price | Free | 30-day trial, then requires a one-time paid license | OS sold bundled with hardware | +| Positioning | Open-source personal
cloud OS that focuses on
helping users deploy and
manage digital assets locally
as an alternative to public
cloud services. | Network storage OS, allows flexible hardware configurations,
simple and convenient management of data, VMs, and Docker applications | Provides secure and efficient data management systems for businesses of different scales,
helping enterprises control growing data streams | + +## Storage features + +| Feature | Olares | Unraid | Synology DSM | +| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- | +| Disk types | System space, user space,
application space, and
application cache are on SSD | System runs on SSD, data stores on HDD |System runs on SSD, data stores on HDD | +| Storage pool | ❌ | Supports Parity-protected array similar to JBOD | Supports SHR, Basic, JBOD, RAID 0, RAID 1, RAID 5, RAID 6, RAID 10, and RAID F1 | +| LAN file sharing | SMB | SMB, NFS | SMB, NFS, AFP, FTP | +| Public file sharing | via Files application | ❌ | via File Station application | +| Distributed file system | ✅ | ❌ | ❌ | +| Mount external cloud drives | Supports mounting Google
Drive, Dropbox, S3, etc. | ❌ | Supports mounting Google Drive, Dropbox, S3, etc. | +| Sync drive | ✅ (Seafile integrated) | ❌ | Synology Drive | +| Mount SMB directory | ✅ | ❌ | ❌ | +| Mount mobile storage devices | Auto-mount | Manual mount | Auto-mount | +| Structured data support | Supports mainstream databases
and data warehouses (e.g., Redis,
PostgreSQL),suitable for production
environments | Can be manually installed,
but not recommended for production environments | Can be manually installed,
but not recommended for production environments | +| Local data security | No protection in single-node;
disk data protection via Minio
or Ceph in cluster mode | Allows 1-2 disk failures depending on configuration,
but Parity disk must not fail | Allows 1-2 disk failures depending on RAID configuration | +| Remote backup | Supports periodic incremental
encrypted backups via Restic | Flash drive can be manually backed up,
but there is no official backup solution for data drives | Supports multiple official backup solutions | + +## Application management + +| Feature | Olares | Unraid | Synology DSM | +| ---------------- | ------------------------------------------------- | ---------------------------------------- | ------------------------------ | +| Installation format | Olares package format based
on improved Helm | Dockerfile or Docker Compose | Dockerfile or Docker Compose | +| App store | Rich community app ecosystem
with application sandboxing | Rich apps with no sandboxing restrictions. | Fewer apps, extendable via third-party stores | +| Application sandbox | ✅ | ❌ | ❌ | +| Developer tools | ✅ (Studio) | ❌ | ❌ | +| Middleware sharing | Supports mainstream middleware like
PostgreSQL, MongoDB, and Redis | ❌ | ❌ | +| Cluster application support | ✅ | ❌ | ❌ | +| LDAP integration | ✅ (Requires third-party adaptation) | ❌ | ❌ | +| Unified SSO login | ✅ | ❌ | ❌ | +| Secret management | ✅ | ❌ | ❌ | + +## Virtual machine management + +| Feature | Olares | Unraid | Synology DSM | +| ------------- | --------------------------------------------------------------------- | ------------------------------ | ------------- | +| Install via ISO | Not yet supported,
will be supported via Kubevirt | ✅ | ✅ | +| Windows | One-click install from
app store, auto-integrates Tailscale,
for secure external RDP access | Install via ISO | Install via ISO | +| Steam | Supported in app store,
auto-configures GPU mounting,
streaming, and external access | Requires manual configuration
for GPU passthrough, etc. | ❌ | +| Linux | Supported via Dev Containers
in Studio | Install via ISO | Install via ISO | +| Android | Supported via redroid | ❌ | ❌ | +| Mac | Coming soon | ❌ | ❌ | +| Openwrt | Coming soon | ❌ | ❌ | + +## Network access + +| Feature | Olares | Unraid | Synology DSM | +| ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| Reverse proxy | Integrated Cloudflare
Tunnel and FRP,
supports independent
domain access for
all apps | Only supports access to limited system services | Only supports access to limited system services | +| DDNS | No configuration
needed | Manual configuration required.
Supports domain+port access for non-system apps,
but practically cannot provide external services. | Manual configuration required.
Supports domain+port access for non-system apps,
but practically cannot provide external services. | +| Custom domain support | ✅ | ❌ | ❌ | +| Firewall | Integrated Cloudflare
firewall | ❌ | ❌ | +| Free HTTPS certificate | ✅ | ✅ | ✅ | +| Two-Factor Authentication Login | ✅ | ✅ | ❌ | +| Different security policies for different directories | ✅ | ✅ | ❌ | +| Private Access Endpoint | ✅ | ✅ | ❌ | +| VPN connection | No configuration needed,
Tailscale integrated | Manual configuration required | Manual configuration required | +| VPN-only access mode | ✅ | ❌ | ❌ | + +## AI capabilities + +| Feature | Olares | Unraid | Synology DSM | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------ | +| GPU management | 1. Supports heterogeneous GPU clusters
across multiple nodes (v1.12)
2. Nvidia GPUs support memory slicing
and time-slicing sharing modes (v1.12) | Supports GPU passthrough on a single node
via manual configuration | ❌ | +| Models | 1. Supports mainstream language, image,
video, and voice models, such as Ollama,
VLLM, ComfyUI, SD, Whisper, and ACE-STEP.
2. Supports mainstream open-source AI tools,
such as Dify, Ragflow, MaxKB, and LobeChat. | ❌ | ❌ | +| Interoperability | 1. Supports mutual calls between
applications and models
2. System-level support for MCP calls (v1.12) | ❌ | ❌ | \ No newline at end of file diff --git a/docs/manual/olares/collaborate.md b/docs/manual/olares/collaborate.md new file mode 100644 index 000000000..e65529dbe --- /dev/null +++ b/docs/manual/olares/collaborate.md @@ -0,0 +1,44 @@ +--- +description: Collaborate effectively in Olares using shared file storage, secure vault sharing, customized application access, and VPN capabilities for seamless remote team workflows. +--- +# Collaborate in Olares +Olares helps teams work together efficiently while maintaining data privacy. Set up your collaborative workspace with some essential features. + +## Access and share files in Files + +Files provides both personal and shared storage spaces: + +* Create shared libraries for team documents and assets. +* Set granular access permissions for different team members. +* Access files seamlessly across desktop and mobile devices. + +For details, see [Sync and share files](./files/sync-share.md). + +## Store and share sensitive information in Vault +Vault lets you store and share sensitive data within your team: + +* Share passwords and credentials securely with team members. +* Create separate vaults for different projects. +* Keep sensitive data private with end-to-end encryption. +* Access shared credentials across desktop and mobile devices. + +For details, see [Share vault items](./vault/share-vault-items.md). + +## Set up application entrances +Give your team flexible ways to access applications through public and private entrances. Public entrances are ideal for team services open to the world (like public websites), while private entrances ensure secure access to internal tools or assets. You can: + +* Replace default route IDs with memorable custom ones (like changing `de463205` to `team-wiki`). +* Set up custom domains for easier team access. + +For details, see [Customize application URLs](./settings/custom-app-domain.md). +## Simplify remote access with VPN +When your team works remotely, accessing Olares usually requires going through public networks - which means using services like Cloudflare and dealing with complex network setups. Olares's built-in VPN offers a simpler way: + +* All team members can access applications on different devices using simple local addresses. +* Instead of going through public networks, connections stay within internal network, making it faster and reducing your public network usage costs. + +For details, see [Access Olares applications on other devices via VPN](/manual/larepass/private-network.md). + + + + diff --git a/docs/manual/olares/controlhub/edit-resource.md b/docs/manual/olares/controlhub/edit-resource.md new file mode 100644 index 000000000..97adc29e5 --- /dev/null +++ b/docs/manual/olares/controlhub/edit-resource.md @@ -0,0 +1,32 @@ +--- +description: Manage Olares system resources efficiently by editing YAML configurations, modifying Pod replicas, and monitoring container status through the Control Hub interface. +--- +# Edit resources via Control Hub +This guide shows you how to edit the resource of specific applications in your Olares environment. + +:::warning +Modifying system resources can significantly impact system stability and performance. Only proceed with modifications under proper guidance and instructions. +::: +## Edit the YAML file + +To edit the YAML file of a workload resource: + +1. In Control Hub, navigate to the application's **Deployments** list, and click a resource to expand its details view. +2. In the top right corner, click **more_vert** > **Edit YAML** to open the YAML editor. +3. Edit the YAML configuration of the workload as needed. +4. Click **OK** to save your changes and apply them. + + ![edit yaml](/images/how-to/olares/controlhub/browse/10.jpg#bordered) + +## Modify Pod replicas + +To modify the number of running Pod replicas: + +1. In Control Hub, navigate to a Pod's resource details page, and locate the number of Pod replicas at the top. +2. Click **add** or **remove** to adjust the number of Pod replicas. + + ![replicas](/images/how-to/olares/controlhub/browse/09.jpg#bordered) + +:::warning +Many applications in Olares do not support multi-replica mode. Increasing the number of replicas for these Pods may cause exceptions. Therefore, it's important to read the documentation thoroughly and adjust the number of replicas with caution. +::: diff --git a/docs/manual/olares/controlhub/index.md b/docs/manual/olares/controlhub/index.md new file mode 100644 index 000000000..07ab76730 --- /dev/null +++ b/docs/manual/olares/controlhub/index.md @@ -0,0 +1,28 @@ +--- +outline: [2, 3] +description: Understand Control Hub UI to manage applications, monitor resources, configure networking, and maintain system settings in Olares. +--- + +# Manage Olares with Control Hub + +Control Hub is the console for Olares, providing developers and users with precise control over system operations and the underlying environment. This guide helps you understand Control Hub's interface and efficiently monitor your resources. + +## Features and components + +Control Hub organizes your system resources and usages into three different groups: + +### Olares + +Monitor the status of applications in three different views: + +- **Browse** (Application-centric view): Navigate through resource usage related to specific applications using a three-column layout for efficient resource location. +- **Namespace** (User-centric view): Access detailed insights into per-user application resource consumption, with sorting and filtering capabilities. +- **Pods**: Monitor pod status and resource consumption at the finest granularity. + +### Resource +View and manage Kubernetes system resources. +- **Networks**: Monitor network security policies implemented in the system and the network connectivity of each namespace. +- **CRDs**: Manages various custom resource declarations in the system. + +### Middleware +View the usage of various middleware services in Olares. diff --git a/docs/manual/olares/controlhub/navigate-control-hub.md b/docs/manual/olares/controlhub/navigate-control-hub.md new file mode 100644 index 000000000..6d88c6080 --- /dev/null +++ b/docs/manual/olares/controlhub/navigate-control-hub.md @@ -0,0 +1,207 @@ +--- +outline: [2, 3] +description: Understand Control Hub components in detail. +--- + +# Navigate Control Hub + +This document walks you through each component of Control Hub in detail. + +## Browse + +The **Browse** section organizes resources into two main namespace categories: + +- User projects include each Olares user's independent namespace. + - `app-{OlaresID}`: community applications installed by user. + - `user-space-{OlaresID}`: Built-in user applications + - `user-system-{OlaresID}`: User-related system programs including TAPR components, schedulers, proxies for cross-application interaction +- System projects include core applications of Olares's cluster, along with system-level service programs. For instance, within `os-system`, there are a Middleware database for the entire cluster, a system-level Vault application, and Authelia, a cluster-wide SSO service. + +:::info +Olares members can only access their own namespaces, while Olares admin can access all user and system namespaces. +::: + +You can view all resource types within the namespace in the second column. + +### Workloads +In Olares, Workloads represent applications running on your Olares cluster. They correspond to three primary resource types in Kubernetes. + +- **Deployment** + - The most common workload type in Kubernetes. + - Automatically generates a `ReplicaSet` to schedule and generate Pods, creating more Pod replicas for horizontal scaling. + +- **StatefulSet** + - Used to deploy `stateful` Pods, such as Pods for databases, distributed file storage, or in-memory caching. + - Each Pod may hold different data, resulting in Pods with different states. Therefore, **StatefulSet** often schedules Pods sequentially. + +- **DaemonSet** + - Schedules and runs only one Pod on each node. The number of Pods generated by a daemon set is usually equal to the number of nodes. + - Used for node-specific hardware operations. + +### Workloads details +![alt text](/images/how-to/olares/controlhub/browse/02.jpg#bordered) +You can view the following information for a workload resource: +- **Details**: The general information of the resource. +- **Pods**: The general information of Pods. +- **Ports**: All exposed port collections from the workload's Pod containers. +- **Environment Variables**: Environment variables defined at the workload level in the Pod template. +- **Labels**: Configured in the `workload` metadata. Used for controller management coordination in Olares. Can also act as indexes for filtering and selecting resources in Kubernetes. +- **Annotations**: Similar to labels but more flexible and character range. Serve as a tool for controllers to manage workloads. +- **Events**: Log of events related to the workload within the latest one hour, often showing Pod scheduling status. + +### Pod details +You can view the following information for a Pod: +- **Details**: The general information of the pod. +- **Containers**: A list of containers within the Pod. +- **Volumes**: Persistent volumes configured for the Pod. +- **Environment Variables**: Environment variables defined for the Pod. +- **Events**: Chronological log of events related to the Pod. + +![containers](/images/how-to/olares/controlhub/browse/04.jpg#bordered) + +### Secrets + +The **Secrets** section stores sensitive data like passwords, credentials, and key configurations. In Kubernetes, this data is Base64 encoded by default. + +![secrets](/images/how-to/olares/controlhub/browse/11.jpg#bordered) + +Expand the **Secrets** section in the second column to see the all secrets under the application's namespace. + +You can view the following information for the secret: + +- **Details**: The basic information of the secret, including the namespace it belongs to and the creation time. +- **Data**: The **Data Key** and **Data Value** of the secret. + +::: tip +The **Data Value** shown by default is the `Base64` encoded. You can click the **preview** button at the top right of this section to see the original text. +::: + +### ConfigMap + +The **ConfigMap** section has a structure similar to **Secrets**. However, the content stored in the **ConfigMap** is saved in plaintext. + +![configmaps](/images/how-to/olares/controlhub/browse/12.jpg#bordered) + +Expand the **ConfigMaps** section in the second column to view the details of the **ConfigMaps** under the application's namespace. + +You can view the following information for the configmap: + +- **Details**: The basic information of the **ConfigMap**, including the namespace and creation time. +- **Data**: The **Data Key** and **Data Value** of the **ConfigMap**. + +### Service accounts + +**Service Accounts** is a Kubernetes mechanism to authenticate cluster container applications, enabling their access to cluster resources managed by **Kubernetes**. + +Each **Service Account** is linked to a **Secret**. This **Secret** includes the **Service Account's** `CA certificate`, `Namespace`, and `Token`. + +![Service accounts](/images/how-to/olares/controlhub/browse/13.jpg#bordered) + +Expand the second column on the **Service Accounts** section to view all the **Service Accounts** under the application's namespace. + +You can view the following information for the service account: + +- **Details**: The basic information of the **Service Account**, including the namespace it belongs to, creation time, etc. +- **Data**: The **Data Key** and **Data Value** of the **Secret** linked to this **Service Account**. +- **Kubeconfig Settings**: The kubeconfig configuration automatically generated by this **Service Account**. Developers can download this configuration and incorporate it into an application within the container. Alternatively, an application in the container can read the **Service Account configuration** injected by **Kubernetes** at `/var/run/secrets/kubernetes.io/serviceaccount/`. + +### Services + +**Services** expose network applications running on a single or a group of Pods as network services. They distribute traffic based on defined Selectors. + +A Selector uses Labels to filter and select Pods. Essentially, a Service acts as a virtual IP (VIP) that directs traffic to a single Pod or a group of Pods. + +![service1](/images/how-to/olares/controlhub/browse/14.jpg#bordered) + +Expand the **Services** section in the second column to view all the Services` under the namespace of the current application. + +You can view the following information for the service: + +- **Details**: The basic information of the Service, including its namespace, creation time, selector, virtual IP, type, and DNS address. +- **Workloads**: All workloads selected by the Service's selector, including name and status. +- **Ports**: All exposed ports, including port number, protocol, and upstream destination port number. +- **Pods**: All Pods selected by the Service's selector, including name, node, IP address, and recent CPU and memory charts. An empty list may indicate a Service issue. +- **Labels**: The Service's labels. +- **Annotations**: The Service's annotations. +- **Events**: All events related to the Service. + +## Namespace + +The **Namespace** section in ControlHub provides a user-centric view of resource consumption and workload conditions on your Olares. + +![namespace](/images/how-to/olares/controlhub/namespace/01.jpg#bordered) + +### Usage Ranking + +**Usage Ranking** organizes system resource consumption by namespace. + +![namespace list](/images/how-to/olares/controlhub/namespace/02.jpg#bordered) + +You can view the following information for the namespace: +- **Quota**: System resource usage percentage of this namespace. +- **Pods**: All pods within the namespace, sorted by resource consumption, with the option to search by keyword. + +### Resources + +The **Resources** section displays a chart of current and historical resource utilization. + +You can view the total resource usage by all users. Alternatively, select a specific user from the dropdown box to view individual resource consumption. + +![resources](/images/how-to/olares/controlhub/namespace/04.jpg#bordered) + +## Pods + +The **Pods** section page provides a comprehensive view of all Pods in your Olares environment, allowing you to manage them at the smallest granularity offered by Kubernetes. + +You can view the following information: +- **Pod List**: All Pods within your Olares. +- **Resource**: A visual representation of the physical resources consumed by your Pods. This view helps you understand how your cluster's resources are being utilized. + +![resources](/images/how-to/olares/controlhub/pods/04.jpg#bordered) + +## Resource + +The **Resource** section includes resources related to both software and hardware in Olares. For software, it encompasses cluster descriptions, feature definitions, and declarations of cluster states, etc. For hardware, it contains details about networks, storage, devices, etc. + +### Network + +![networks](/images/how-to/olares/controlhub/resources/01.jpg#bordered) + +**Network Policies** is one of the most important network resource in Olares. They define how the network connects. The system utilizes a **sandbox mechanism** for network policies, which restricts interactions based on the namespace. This provides isolation between the networks of different users and applications. + +#### Ingress Rule + Shows a list of rules that specify which `incoming traffic` is allowed into a Namespace: +* Only the traffic from the pod in the `namespace`, which matches the label specified in the rule, is allowed.
+* The `AND` logic is applied for each label within a rule.
+* he `OR` logic is applied between the rules in the list. + +#### Egress Rule + Similar to the Ingress Rule, it also displays a list of rules that specify which `outgoing traffic` is allowed out of a Namespace. + +### CRDs + +![CRDs](/images/how-to/olares/controlhub/resources/02.jpg#bordered) + +CRDs list all the Kubernetes-based Custom Resource Definitions (CRDs) in Olares. Many cloud-native features of Olares depend on these CRDs. +You can see the following information for the CRDs: +- **Details**: Shows the name, group, scope level, and creation time of the CRD. There are two types of CRD scopes: + + - **Namespace**: Indicates that each custom resource belongs to a namespace. + + - **Cluster**: Indicates that each custom resource must be globally unique and does not belong to any Namespace. For instance, the Namespace itself is a resource at the cluster level. + +- **Custom Resource**: All the custom resources under this CRD, including their names and creation times. + +## Middleware + +The **Middleware** section allows you to manage middleware in Olares. + +:::tip +Only administrators can access the **Middleware** page. +::: + +You can see the following information for the middleware: +- **Details**: Cluster data, including cluster name, deployment namespace, access address, and administrator password. +- **Database**: An overview of the databases utilized by different applications within Olares, including database name, user, and passwords. + +![postgres](/images/how-to/olares/controlhub/middleware/01.jpg#bordered) \ No newline at end of file diff --git a/docs/manual/olares/controlhub/view-container.md b/docs/manual/olares/controlhub/view-container.md new file mode 100644 index 000000000..3ba1c759c --- /dev/null +++ b/docs/manual/olares/controlhub/view-container.md @@ -0,0 +1,35 @@ +--- +description: Troubleshooting application issues status by examining the container staus or exporting logs +--- +# Examine container status + +The Pods page provides a comprehensive view of all Pods in your Olares environment, allowing you to manage them at the smallest granularity offered by Kubernetes. + +This guide shows you how to check the status and export logs of your containers. + +## View container status + +Click on a Pod in the list takes you to the Pod details page, where you can: +- View container logs. +- Access the container environment. +- View container ports and environment variables. +- Open the Pod's YAML configuration in a read-only view. + :::tip + You cannot edit the YAML configuration directly from this view. The YAML is managed by Olares through workload templates and webhooks. + ::: + ![pod detail](/images/how-to/olares/controlhub/pods/02.jpg#bordered) + +## Export container logs for troubleshooting + +To effectively diagnose and resolve issues, you may need to examine detailed logs from your containers. + +![pod detail](/images/manual/olares/controlhub-export-log.png) + +1. In the Browse column, navigate to your application, then go to **Deployments** > **Containers**. +2. Locate the container that's experiencing issues (with an orange dot). +3. Click the article button next to the container. +4. In the pop-up log window, you have the following options to manage the logs: + ![Log operations](/images/manual/olares/controlhub-log.png) + - Click the download_2 button to download the entire log file. + - Click the autorenew button to refresh and see the latest log entries. + - Click the play_pause button to start or pause the log updating in real-time. diff --git a/docs/manual/olares/desktop.md b/docs/manual/olares/desktop.md new file mode 100644 index 000000000..65a706b1a --- /dev/null +++ b/docs/manual/olares/desktop.md @@ -0,0 +1,72 @@ +# Get familiar with Desktop + +The Desktop application serves as the primary interface for user interaction with the Olares system. It offers an intuitive and efficient way to manage and utilize both built-in system applications and those you install. + +## Desktop concepts + +![Desktp[]](/images/manual/olares/desktop.png) + +### Dock & Launchpad + +* **Dock:** An application quick-launch bar located on the side of the screen. +* **Launchpad:** Accessed by clicking the "Launchpad" icon on the Dock, it displays all installed applications. + +### Application windows + +* Applications open in "window" mode by default. +* Windows support standard operations: dragging, resizing, minimizing, maximizing, and closing. +* **Search:** Enables quick application launching, file searching, and more. + +## Use the Launchpad + +From the Launchpad, you can: + +* View all installed applications. +* Click an application icon to open it. +* Drag icons to reorder them within the Launchpad. +* Drag an icon to the Dock for quick access. + +### Uninstall applications + +1. Press and hold an application icon to enter the editing mode. +2. If an "X" appears in the top-right corner of the application icon, click it to delete the application. + +::: tip Note +Built-in system applications such as Files, Market, and Profile cannot be uninstalled. +::: + + +### Controll application windows + +You can access applications via two modes. + +By default, applications open in "window" mode, which is an iframe page embedded within the desktop. You can manipulate these windows much like standard computer windows: + +* Drag the title bar to move the window. +* Drag the window's edges to resize it. +* Minimize, maximize, or close the window. +* Click the open_in_new button to open the application in a new browser tab. + +::: tip Note +Some applications only support opening in a tabbed view. +::: + +## Search within Olares + +You can quickly call out global search using one of the following methods: + +* Press the keyboard shortcut: `Shift + Space` +* Click the "Search" icon in the Dock. + + +| Search target | Supported actions | +|:--------------------------------------------|:----------------------------------------------------------| +| Installed Applications | Open the application directly. | +| Documents directory in File Manager Storage | Search by filename or full-text content. | +| Other directories in File Manager Storage | Search by filename only. | +| File Manager Synced Drive | Search by filename only. | +| Wise Reader Content | Search full-text content of RSS feeds, web pages, & PDFs. | +| **More** | | +| Settings | Adjust Olares appearance. | +| Applications | Install, uninstall, or update applications. | + diff --git a/docs/manual/olares/files/add-edit-download.md b/docs/manual/olares/files/add-edit-download.md new file mode 100644 index 000000000..766b17341 --- /dev/null +++ b/docs/manual/olares/files/add-edit-download.md @@ -0,0 +1,114 @@ +--- +description: Learn essential file operations in Olares including adding new files, editing existing content, and downloading files across different devices. +--- +# Basic file operations +Operations in Fileare essentially the same as in other file managers. This page will introduce some common tasks in Files to get you started. + +## Upload files + +### Upload via the Files app +1. Open the Files app from the Dock or Launchpad on Olares. +2. In the left sidebar, select the directory where you want to upload files. For example, **Documents**. +3. Upload multiple files or folders using one of these methods: + - Drag and drop files from your local file manager into the Files window. + - Click drive_folder_upload in the top right corner. + - Right-click in an empty space and select from the context menu. + +:::info +Files supports resumable uploads. If an upload is interrupted, it will automatically resume from the last checkpoint. +::: + +### Upload via LarePass desktop +:::info Import your Olares ID +To start using LarePass desktop, you must import your Olares ID by pasting your mnemonics. Make sure you have [backed up your mnemonics](/manual/larepass/back-up-mnemonics.md). +::: +LarePass desktop offers the same upload experience as the Files app, with automatic syncing to your Olares ID. + +### Upload via LarePass mobile +You can also upload files or folders on your phone via the LarePass app. + + + + + + +Files uploaded via the LarePass mobile app will also sync automatically with your Olares ID. + +## Download files +When downloading multiple files, the behavior differs between the Files in Olares and LarePass desktop application. +* **Files in Olares (web interface)**: Download tasks are managed directly in your browser. Manage the download queue, pause, resume, or cancel a download in the download manager of the browser. +* **LarePass desktop**: Downloads are queued in LarePass, allowing you to pause, resume, or cancel tasks, and easily locate downloaded files. +:::tip Notes +- Folder download is only supported in LarePass desktop. +- For large files or multiple downloads, it's recommended to use the LarePass desktop application for more powerful download management and a better user experience. Visit the [official page](https://olares.com/larepass) for details and download options. +::: + +1. Open the Files app from the Dock or Launchpad on Olares. +2. Select any file, right-click to open the context menu, and select **Download**. +3. Select the save location in the popup window. + +## Preview and edit files +Double-click a file to open its preview. The Files app supports previewing the following file formats: + +* **Images**: JPG, JPEG, PNG, BMP, WEBP, SVG +* **Videos**: MP4, MKV, AVI, MOV, MPEG, MTS, TS, WMV, WEBM, RM, 3GP +* **Audio**: MP3, WMA, WAV, OGG, AAC, M4A, APE, FLAC +* **Text**: PDF, TXT, JS, CSS, XML, YAML, HTML + +The Files app also supports editing the following text formats: TXT, JS, CSS, XML, YAML, HTML. + +![Preview](/images/manual/olares/files-preview.png#bordered) +## Search files +You can easily find files in the Files app using desktop search. +:::tip +Full-text search is available for the `/Documents/` directory in **Drive**, allowing you to search within file contents. For other directories, you can search files using their file names. +::: +1. Click searchin the Dock to open the search window. +2. In the search field, enter keywords related to the file you're looking for. +3. Use arrow keys arrow_upwardarrow_downward to select the search scope: **Drive** or **Sync**, and press **Enter** to see search results. + +![Search](/images/manual/olares/files-search.png#bordered){width="90%""} +## Delete files +:::warning +Deleted files cannot be recovered. +::: +1. Open the Files application from the Dock or Launchpad on Olares. +2. Select the file(s) you want to delete and choose one of these methods: + - Right-click and select **Delete** from the context menu. + - Click more_horiz in the top right corner and select **Delete**. +3. Confirm the deletion in the popup window. + +## Change display view + +Switch between list view and grid view to display your files and folders differently. + +![Display view](/images/manual/olares/files-display-view.png) +## Shortcuts +To select multiple files: + +* **On Windows**: Control + click +* **On Mac**: Command + click diff --git a/docs/manual/olares/files/index.md b/docs/manual/olares/files/index.md new file mode 100644 index 000000000..b27d70473 --- /dev/null +++ b/docs/manual/olares/files/index.md @@ -0,0 +1,45 @@ +--- +description: Manage files efficiently in Olares with secure storage, seamless synchronization across devices, and centralized file management capabilities. +--- +# Manage files in Olares + +Olares's built-in Files app offers users a secure and efficient solution for file storage and synchronization, allowing access to various file types from any device or browser. It has the following advantages: + +* **Access anywhere**: View, download, or share files stored in Olares from any location using any device or browser. +* **Seamless synchronization**: Ensures data remains up-to-date across all your devices. +* **Centralized storage**: Simplifies information retrieval and integration, making it easier to access, manage, and update your data, whether personal documents or team-shared materials. + +## Understand the interface +The interface is similar to Windows Explorer or macOS Finder, allowing you to organize and access documents, images, videos, or any other files you own. + +![Files](/images/manual/olares/files.png#bordered) + +It consists of three main components: + +* **Drive**: For storing files that don't require frequent synchronization or modifications. +* **Sync**: For syncing files and directories across devices. +* **Application**: For development and debugging purposes only. +* **CloudDrive**: For mounting and accessing your cloud storage services including Google Drive, AWS S3, Tencent Cloud Object Storage (COS) + +--- +
+

Basic file operations

+Learn the fundamentals of file management in Olares. +
+ +
+

Sync and share files

+Learn how to keep files updated across devices, and how to share files with other Olares member. +
+ +
+

Mount SMB

+Learn how to mount and access SMB shared folders from NAS devices or network servers in Olares. +
+ +
+

Mount cloud storage

+Learn how to mount and access third party cloud storage services in Olares +
+ + diff --git a/docs/manual/olares/files/mount-SMB.md b/docs/manual/olares/files/mount-SMB.md new file mode 100644 index 000000000..86201e603 --- /dev/null +++ b/docs/manual/olares/files/mount-SMB.md @@ -0,0 +1,31 @@ +--- +description: Learn how to mount and access SMB shared folders from NAS devices or network servers in Olares. Step-by-step guide for connecting to SMB shares and managing network files. +--- +# Mount SMB shares +SMB (Server Message Block) is a protocol used to share files, printers, and other resources over a network. If you have a network-attached storage (NAS) device or another SMB server in LAN, you can easily mount SMB shares in Olares to access and manage shared files. + +## Before you begin +- Your Olares and the SMB server (e.g. a NAS device) must be on the same local network. +- You have the following SMB share details: + - **SMB share path**: This will typically look like `\\\`. + - **Username and password**: Credentials for accessing the SMB share. + +## Mount SMB share to Olares +1. Open Files, and navigate to **Drive** > **External**. +2. Click **Connect to server** in the top-right corner. +3. Enter the SMB share path (e.g., `\\192.168.1.100\Documents`) in the **Server Address** field and click **Submit**. + :::tip Save frequently used server addresses + - To add a server address to **Favourite Servers**, click add after entering the share path. + - To remove a saved server, click the server path under **Favourite Servers**, then click remove. + ::: + ![Add SMB share path](/images/manual/olares/add-SMB-share-path.png#bordered) +4. Enter the username and password, then click **Submit**. + +Once connected, the SMB share will appear in **External** directory, allowing you to access shared files and folders seamlessly. + +## Unmount SMB share +To unmount an SMB share: +1. Open Files, and navigate to **Drive** > **External**. +2. Right-click on the mounted folder, then select **Unmount** from the context menu. + +The SMB share will be safely disconnected from your Olares. \ No newline at end of file diff --git a/docs/manual/olares/files/mount-cloud-storage.md b/docs/manual/olares/files/mount-cloud-storage.md new file mode 100644 index 000000000..43e20c101 --- /dev/null +++ b/docs/manual/olares/files/mount-cloud-storage.md @@ -0,0 +1,34 @@ +--- +description: Learn how to mount and access cloud storage services in Olares. +--- +# Mount and use cloud storage + +You can easily mount a cloud storage through the **Integration** function in Olares, and access and manage your cloud files directly in the **Files** application. + +![Cloud storage](/images/manual/olares/files-cloud.png) + +## Mount a cloud storage + +To mount a cloud storage, connect to it in **Integrations** in LarePass or Olares Settings: + +* **OAuth-based storage services**: Google Drive and Dropbox. Connect via [**LarePass** app](../../larepass/integrations.md#add-a-cloud-drive-via-oauth). +* **API credential-based services**: AWS S3 or Tencent Cloud Object Storage (COS); Connect via [LarePass app](../../larepass/integrations.md#add-a-cloud-storage-using-api-keys) or [Olares Settings](../settings/integrations.md#add-cloud-object-storage-via-api-keys). + +Once connected, the cloud storage will be automatically mounted under **Cloud Drive** in **Files**. + +## Access a cloud storage + +Once mounted, you can access and manage files just as you would with local storage: + +* **Upload / Download** files +* **Preview** supported file types +* **Rename**, **move**, or **delete** files and folders + +Changes made in the Files app will sync with your remote storage provider. + +## Unmount a cloud storage + +You can unmount a cloud storage by removing the corresponding integration: + +* [Remove integration in LarePass](../../larepass/integrations.md#disconnect-integrations) +* [Remove integration in Olares Settings](../settings/integrations.md#view-and-manage-existing-integrations) diff --git a/docs/manual/olares/files/sync-share.md b/docs/manual/olares/files/sync-share.md new file mode 100644 index 000000000..84890160b --- /dev/null +++ b/docs/manual/olares/files/sync-share.md @@ -0,0 +1,123 @@ +--- +description: Keep files synchronized across devices and share content securely with other Olares members using built-in file sharing capabilities. +--- +# Sync and share files +LarePass is a powerful tool not only ensures your Files content remains consistent and accessible, but also facilitates seamless collaboration within your Olares server. + +This page will mainly cover: +- How to sync files across devices +- How to share files with other team members + +## Understand Sync and Library +### Sync +Sync in the Files app is similar to cloud storage services like iCloud, where you can keep your most important information up to date, and available across all your devices. Sync also makes it easy to share files with other members within an Olares server. + +### Library +Library is the fundamental unit for organizing, syncing, and sharing your digital content. It is more than just a folder. It's a versatile container designed to meet various data synchronization and sharing needs: + +* **Multi-device synchronization**: Libraries ensure your data remains consistent across all your devices. +* **Real-time collaboration**: Share libraries with other users, enabling simultaneous access and editing of data within the same Library. +* **Flexible management**: Create multiple libraries to organize different types of data or for various projects, giving you granular control over your synchronization and sharing preferences. + +### Roles and permissions +:::info +The roles and permissions described here are specific to file sharing and Library management within Files. These are distinct from the overall Olares user roles and system-wide permissions. +::: + +| Operation | Owner | Member | +|----------------------------|-------|--------| +| Create Library | ✅ | ✅ | +| Manage Library permissions | ✅ | ❌ | +| Invite other members | ✅ | ❌ | +| Share and rename Library | ✅ | ❌ | +| Remove members | ✅ | ❌ | +| Delete Library | ✅ | ❌ | +| Exit Library | ❌ | ✅ | + +Permission levels: +- **Read-only**: Users can view Library contents but cannot modify them. +- **Read-write**: Users can add, delete, and modify Library contents. + +## Before you begin +Make sure you have installed the LarePass desktop client from the [official website](https://olares.com/larepass), and logged in using your Olares ID. + +:::info +Currently, local file sync is available for Windows and Mac users. We'll use the Mac version for our examples. +::: + +## Create a Library +Each user is automatically provided with their own personal Library as a starting point. To create a new Library: + +1. In the left sidebar under **Sync**, click the add_circle to open the **New library** dialog. +2. Enter a name for the Library and click **Create**. + +## Sync Library files to local + +1. Open LarePass on your Mac. +2. Locate your desired Library and click more_horiz > **Sync to local**. +3. Select your preferred local directory, and click **Complete**. +4. To initiate the sync, click more_horiz > **Sync now**. + +Once synchronized, your libraries will display a green icon, indicating active two-way synchronization. Any changes made locally will automatically reflect in your synced Library. + +## Sync local files to Library +:::info +If your permission to the Library is read-only, you cannot sync changes from the local folder to the Library. Your newly added and modified files will be read-only, indicated by a gray disabled icon remove. +::: + +To sync an existing local folder on your Mac, simply create a matching Library in LarePass and move your files into the designated sync directory. + +This approach allows you to maintain your current folder structure while benefiting from LarePass's synchronization capabilities. + +## Managing sync settings +If you need to pause or stop synchronization for a specific Library: + +1. Locate the Library in LarePass. +2. Click more_horiz > **Unsynchronized**. + +Rest assured, this action won't delete your local files. It simply halts the two-way synchronization process. + +## Share a Library +:::tip +To add a member in Olares, see [manage team](../settings/manage-team.md). +::: + +You can share a Library with other members within an Olares server: + +1. Select a Library, and click more_horiz > **Share with**. +2. In the dialog, select users from the dropdown menu, and click **Share to user**. +3. Set file permissions for each user: **Read-write** or **Read-only**. +4. Click **Close**. + + ![Share library](/images/manual/olares/share-library.png#bordered){width="50%"} + +Invited users will see the shared Library in their Sync content list. To revoke sharing permissions, simply remove the user from the sharing window. + +## Exit or delete a Library +If you don't want to share a Library, you could exit sharing or delete it. +- **Exit sharing**: Any member can exit a shared Library. When an owner exits, the Library will appear in their personal Library list. +- **Delete**: Only the owner can delete a shared Library. + :::warning + Deleting a Library is irreversible. All files in the shared Library will be permanently deleted. + ::: + +1. To exit a Library: + + a. Select a shared Library and click more_horiz > **Exit sharing**. + + b. Click **Confirm** in the popup dialog. +2. To delete a Library: + + a. Select a shared Library and click more_horiz > **Delete**. + + b. Click **Confirm** in the popup dialog. + +## Handle sync conflicts + +In the rare event of a sync conflict, LarePass has you covered. When multiple devices edit the same file simultaneously: + +* The first completed edit is saved to the Library. +* A backup of the conflicting version is created with a unique filename, including the editor's Olares ID and timestamp: `test.txt(SFConflict name 2024-04-17-12-12-12)`. + +## Learn more +- [Manage team](../settings/manage-team.md) \ No newline at end of file diff --git a/docs/manual/olares/index.md b/docs/manual/olares/index.md new file mode 100644 index 000000000..38b317ba7 --- /dev/null +++ b/docs/manual/olares/index.md @@ -0,0 +1,30 @@ +--- +description: Learn how to use Olares system applications with step-by-step guides covering personalization, application management, file handling, security setup, and team collaboration features. Updated regularly with the latest Olares functionality. +--- +# Olares system applications + +Olares system applications are a core component of the Olares ecosystem, pre-installed on your Olares to provide a fundamental yet powerful set of tools. These applications are designed to help you efficiently manage files and applications, organize knowledge, configure system, and accomplish many other daily tasks. Understanding the functions and value of these system applications will enable you to fully leverage Olares' potential, creating a personal cloud environment tailored to your personal needs. + +This document serves as your comprehensive guide to exploring Olares system applications, empowering you to better navigate your Olares system. + +## What can you do with system applications? + +Explore the following guides to get the most out of Olares’s built-in apps: + +[**Navigate and customize your Desktop**](./desktop.md): Launch apps, organize your workspace, and search across Olares. + +[**Install and manage apps with Market**](./market.md): Discover, install, update, or remove apps and recommendation algorithms from an open permisionless application store. + +[**Store, sync, and access Files**](./files/): Upload, download, organize, and share files securely across devices with centralized storage and real-time synchronization. + +[**Secure and manage passwords with Vault**](./vault/): Store credentials, manage digital identities, and generate OTPs in a powerful, secure password management tool. + +[**Collect and curate knowledge with Wise**](./wise/): Collect, consume, and manage content from various platforms, get personalized recommendations, creating and maintaining your personal information hub. + +[**Configure and customize your Olares with Settings**](./settings/): Set up users, apps, network, integrations, security, appearance, backups, and more, all from one centralized interface. + +[**Monitor and control Olares environment with Control Hub**](./controlhub/): Monitor system status, manage application services, and fine-tune your Olares environment from a single console. + +[**Learn system status with Dashboard**](./resources-usage.md): View real-time resource usage and performance metrics in an easy-to-understand interface. + +[**Design your unique Olares Profile**](profile.md): Customize your personal homepage on Olares to reflect your identity and share with others. \ No newline at end of file diff --git a/docs/manual/olares/market.md b/docs/manual/olares/market.md new file mode 100644 index 000000000..b89be47d2 --- /dev/null +++ b/docs/manual/olares/market.md @@ -0,0 +1,110 @@ +--- +outline: [2, 3] +description: Complete guide to managing Olares applications - install from Market, update system and community apps, handle custom installations, and properly uninstall applications. +--- + +# Manage applications in Market + + Olares Market is an open and permissionless application platform. It provides one-click installation for a variety of applications and content recommendation algorithms from both Olares and third-party developers. + +This guide helps users understand how to install, update, and uninstall applications through the Market. We'll also cover how to install custom applications. + +## Before you begin +Before you start, it is recommended to familiarize yourself with a few concepts for Olares applications: + +| Terminology | Description | +|-----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [System application](../concepts/application.md#system-applications) | Built-in applications that come pre-installed with Olares,
such as Profile, Files, and Vault. | +| [Community application](../concepts/application.md#community-applications) | Applications that are created and maintained by third-party
developers. | +| [Shared application](../concepts/application.md#cluster-scoped-applications) | A special category of community applications on Olares
designed to provide unified, shared resources or services to all
users within an Olares cluster. Only one
instance is allowed per cluster. | +| [Reference application](../concepts/application.md#reference-applications) | The applications that have been granted access to specific
shared applications | +| [Dependencies](../concepts/application.md#dependencies) | Prerequisite applications that must already be
installed before a user can access an application
that requires them. | + +## Find applications +The Olares Market offers various ways to discover and browse applications: + +On **Discover** page: +* **Featured Applications**: Curated by the editorial team, showcasing trending and seasonally relevant apps. +* **Community choices**: Most loved and recommended apps by the Olares community. +* **Top apps**: Apps with the highest usage and download rates. +* **Latest apps**: Recently added applications to the market. + +You can also browse applications based on their functionality: +* **Productivity**: Apps for work scenarios and improving efficiency. +* **Utilities**: Tools for solving specific problems or completing tasks. +* **Entertainment**: Apps for leisure and enjoyment. +* **Social network**: Platforms for connecting with others. +* **Blockchain**: Applications related to blockchain technology. +* **Recommendation**: Decentralized content recommendation algorithms for Wise. + :::info + For information on using the recommendation feature in Wise, refer to [discover themed content](./wise/recommend). + ::: + + ![Market](/images/manual/olares/market-discover.png#bordered) +## Install applications + +1. Open the Market app from the Dock or Launchpad. +2. Navigate to the app you want, and click **Get**. +3. When the operation button changes to "**Install**", click it to start the installation. +4. Once finished, the button will change to "**Open**". + +:::tip +To cancel an installation, hover over the operation button and click **Cancel** when it appears. +::: + +### Install shared and reference applications + +To ensure a shared service is running and accessible within the cluster, follow this general installation process based on the type of Shared App: + +* **Headless backend service**: + This type of shared applications typically require third-party reference applications to access its service. Take Ollama for example: + 1. The administrator installs the shared application first. This makes the core service available in the cluster. + + 2. Members (including the administrator) install the corresponding reference application (e.g., Open WebUI or LobeChat) to access the Ollama service. + +* **Complete application with built-in UI**: + This type of shared applications can provide service to itself. Typical examples are Dify Shared and ComfyUI Shared. + + 1. The administrator installs the shared application first. This not only launches the shared service for the cluster, but also installs the client-side interface as the reference application. + + ::: tip ComfyUI Launcher + ComfyUI Shared contains a web launcher component to facilitate the management of related services and resources. The administrator needs to configure and start the service from the ComfyUI Launcher. + ::: + + 2. Other members in the cluster install the same application. For these users, only the access point to the shared application is installed. + +### Install custom applications + +1. Prepare an Olares Application Chart file (in `.zip`, `.tgz`, `.tar`, or `.gz` format). +2. Open the Market app from the Dock or Launchpad. +3. Click **My Olares** > **Custom** to see all custom applications. +4. Click **Upload custom chart** and select chart files. + +## Update applications +1. Open the Market app from the Dock or Launchpad. +2. Click for update notifications besides **My Olares** from the left sidebar. + If there is an available update, you should see a label marked with number. +3. Click **My Olares** > **Available updates** to see all updatable applications. +4. Click **Update all** to update all applications at once, or update each application individually. + +## Uninstall applications + +### Uninstall from Market +1. Open the Market app from the Dock or Launchpad. +2. Click **My Olares** from the left sidebar to view all installed apps. +3. Click keyboard_arrow_down next to the application's operation button, and select **Uninstall**. + +### Uninstall from Launchpad +1. In Olares, click Launchpad icon in the Dock to display all installed apps. +2. Click and hold the app icon until all the apps begin to jiggle. +3. Click cancel on the app icon to uninstall it. + + +## FAQ + +### Why can't I install an application? +If you can't install an application, it might be due to: +* **Insufficient system resources**: Try freeing up system resources, or increasing your resource quota. +* **Missing dependencies**: Check the **Dependency** section on the application details page and make sure all required apps are installed. +* **Incompatible system version**: Try upgrading Olares to the latest version. +* **Shared application restrictions** (for Olares member): Install the reference app, and contact your Olares admin to install the corresponding shared application. diff --git a/docs/manual/olares/nft-image.md b/docs/manual/olares/nft-image.md new file mode 100644 index 000000000..5b2319b12 --- /dev/null +++ b/docs/manual/olares/nft-image.md @@ -0,0 +1,43 @@ +--- +description: Add unique NFT images as your Olares profile picture by connecting your blockchain wallet, importing NFTs, and setting them as custom avatars. +--- +# Add NFT image as profile picture +Olares allows you to use NFT (Non-Fungible Token) images as unique avatars for your profile, adding a personalized touch to your digital identity. This feature requires connecting a blockchain wallet to your account. + +## Before you begin +Before you begin, [connect your Olares with Olares Space](./settings/integrations.md). + +## Step 1. Set up blockchain wallet +1. Find and install the MetaMask extension from the Chrome Web Store. +2. Create a new wallet or import an existing one. +3. Follow the on-screen instructions to set up your MetaMask wallet. + +## Step 2. Import blockchain wallet +1. In Olares, open the Settings app from the Dock or Launchpad. +2. Select **Integration** from the left sidebar, and click on the Olares Space card on the right. +3. Click **Import**, and follow the on-screen instructions to connect your MetaMask wallet. + +After importing your wallet, the page will refresh to display wallet details. + +## Step 3. Associate Olares ID + +1. Click **Bind**, and confirm this action in MetaMask. + This will also trigger a confirmation prompt in LarePass app. +2. Open the LarePass app. You should see a confirmation prompt. If not: + + a. Go to **Settings** > **Integration**. + + b. Tap the Olares Space card. + + c. In the confirmation prompt, tap **Confirm** to authorize. +3. Return to Olares, and click **Confirm** to complete the association to your Olares ID. + +Now you should be able to access your NFT collection in Olares. + +## Step 4. Select an NFT as your profile picture +To use your preferred NFT image and set it as your unique avatar: +1. Open the Profile app. +2. In the **Header** page, click the avatar image under **Profile picture**. +3. In the dialog, click **NFT Avatar**. +4. Select an image from your NFT collection. +5. Click **Create** to apply the change. \ No newline at end of file diff --git a/docs/manual/olares/profile.md b/docs/manual/olares/profile.md new file mode 100644 index 000000000..e46c0d3e6 --- /dev/null +++ b/docs/manual/olares/profile.md @@ -0,0 +1,31 @@ +--- +outline: [2, 3] +description: Create and customize your Olares personal homepage with a unique cover design, social media links, custom layouts, and monitor its performance with powerful analytics tracking capabilities. +--- + +# Design Your Olares profile + +You can create a distinctive personal homepage that showcases your digital identity. + +![Profile](/images/manual/olares/profile.png) + +## Access your homepage +Your personal homepage's default URL is `{Local name}.olares.com`. + +## Customize your homepage + +### Design your cover +Craft your homepage's header to reflect your style. You can build your content using various elements such as text, images, and link sections, much like assembling building blocks. + +### Add social media links +Enhance your online presence by adding social media links. Visitors can easily access your profiles by clicking the corresponding icons on your homepage. + +### Choose your layout +Fine-tune your homepage's appearance by adjusting the layout style and background scheme in the appearance section. + +## Share your homepage +Olares offers multiple ways to share your personal homepage: + +* **Share via social platforms**: Directly share your homepage on popular social media platforms like X, Meta, and LinkedIn. +* **Share via QR code**: Generate a QR code for your homepage, which you can download and share. +* **Share as a digital business card**: Create a stylish digital business card featuring your homepage URL, perfect for networking. \ No newline at end of file diff --git a/docs/manual/olares/resources-usage.md b/docs/manual/olares/resources-usage.md new file mode 100644 index 000000000..98e0e60a3 --- /dev/null +++ b/docs/manual/olares/resources-usage.md @@ -0,0 +1,87 @@ +--- +outline: [2, 3] +description: Monitor your Olares system and application performance with comprehensive dashboards tracking CPU, memory, and disk usage for optimal resource management. +--- + +# Monitor system and application status +The Dashboard app in Olares works similarly to Windows Explorer, providing a centralized view of your system's status without requiring technical expertise. From the main dashboard, you can view resource usage patterns and detailed metrics. +:::info +When applications in your Olares are exposed to the public internet, they generate FRP traffic costs from external access. To monitor these costs and traffic, see [VIew system status](../../space/manage-olares#view-system-status). +::: + +## Access monitoring dashboards +View your system's status through these specialized dashboards: +- **Overview**: Shows current resource usage and system health. +- **Applications**: Displays running applications and their status. + +## Overview + +### View physical resources + +Monitor four fundamental metrics directly from **Overview**: +- CPU utilization +- Memory consumption +- Disk usage +- Pod status + +![Dashboard overview](/images/manual/olares/dashboard-overview.png#bordered) +### Access detailed metrics + +For deeper analysis, click **More details** to view comprehensive monitoring data for the past 7 days. + +Use the dropdown menu in the top right to change the time range, or click refresh to update monitoring data. + +The following metrics help you maintain optimal system performance: + +| Metric | Description | Impact | +|------------------|------------------------------------|-----------------------------------------------| +| CPU usage | Percentage of CPU resources used | Prolonged spikes can slow down the system | +| Memory usage | Percentage of memory in use | Impacts application performance and stability | +| Average CPU load | Average number of active processes | High load indicates system overload | +| Disk usage | Percentage of disk space used | Crucial for data reliability, prevent overuse | +| Inode usage | Percentage of inodes used | Exhaustion prevents new file creation | +| Disk throughput | Data transfer rate (MB/s) | Important for large file transfers | +| IOPS | Input/Output Operations Per Second | Critical for small file or random data access | +| Network traffic | Network usage (Mbps) | Reflects network speed and quality | +| Pod status | Count of pods by state | Reflects application health | + +![Physical resource monitoring](/images/manual/olares/physical-resource-monitoring.png#bordered) +### Check resource quota +You can view your resource quota allocated by the Olares admin. + +![Resource quota](/images/manual/olares/resource-quota.png#bordered) + +:::warning +When your resource quota runs low, you may experience: + +* Slower system performance. +* Inability to install new applications. +* Automatic suspension of resource-intensive applications. +::: + + +### Track application performance +The **Usage ranking** section displays the top 5 applications consuming CPU and memory resources. To access the complete list of application resource usage, click **More**. + +![Usage ranking](/images/manual/olares/usage-ranking.png#bordered) + +## Applications + +The **Applications** dashboard helps you monitor resource usage patterns across your applications through various sorting and filtering options. + +Use the dropdown menu in the upper right corner to sort applications based on their resource consumption: +- CPU usage +- Memory usage +- Inbound traffic +- Outbound traffic + +![Applications](/images/manual/olares/applications.png#bordered) + +Toggle between ascending and descending order to identify which applications are consuming the most or least resources. + +For applications supporting multiple entrances (such as Wordpress), you can click icons to switch between different entrance types and view their corresponding resource metrics. +![Multiple entrances](/images/manual/olares/multiple-entrances.png){width=40%} +:::tip +* When your application list grows large, quickly locate specific applications by typing their names in the search box at the top of the page. +* Regularly checking resource consumption patterns helps you identify applications that might need optimization or attention. +::: \ No newline at end of file diff --git a/docs/manual/olares/settings/backup.md b/docs/manual/olares/settings/backup.md new file mode 100644 index 000000000..23062cbbb --- /dev/null +++ b/docs/manual/olares/settings/backup.md @@ -0,0 +1,63 @@ +--- +description: Learn how to create and manage backups for your important files and apps on Olares. +--- +# Backup your data in Olares + +Olares' backup feature lets you create full and incremental backups for specified file directories and the Wise application. You can choose to back up your data on both local and network storages, with options to set up automatic backup schedules. + +## Add a backup task + +To add a backup task: + +1. Go to **Settings › Backup**, and click **Add backup task**. +2. Choose **Backup files** or **Backup applications**. +3. On the **Add backup task** page, configure the following options: + + | Option | Description | + |:-----------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| + | **Backup location** | - **Local path**: Recommended to select an external
device such as a USB drive, SMB share, or external
hard drive.
- **Cloud storage**: Supports Olares Space, AWS S3, and
Tencent COS. Accounts can be added via **Settings ›
Integrations** or directly in the dialog by clicking
**Add account**. | + | **Region** (for network storage) | Choose the region for the selected storage service. | + | **Backup path** (for file backups) | Specify the directory to back up. | + | **Select application** (for app backups) | Choose the application to back up from the dropdown.
Currently, only **Wise** is supported. | + | **Backup name** | Enter a recognizable task name. Recommended to
include the purpose and timestamp. | + + :::warning + Ensure the selected storage has enough available space to store the backup data. + ::: + +3. Set backup schedule & security: + - **Snapshot frequency** – Choose from daily / weekly / monthly + - **Snapshot time** – Set the time when the backup task should run + - **Backup password** – Protect your snapshots with a password + +4. Click **Submit** to start the backup task. The first execution will perform a **full backup**. Subsequent runs will perform **incremental backups**. + + :::warning + Before starting the backup, please make sure: + + - The selected storage has enough available space to store the backup data; + - You have an active subscription for the selected cloud storage service; + - You have read and write permissions for the target storage location, for example, an SMB directory. + + +## Manage backup tasks + +Once created, your backup task will appear in the task list. Click the **>** button on the right to open the detail page. Available actions include: + +| Action | Description | +|:-----------------|:--------------------------------------------------------------------------------------------------------------------------| +| **Manage** | - **Edit**: Modify the snapshot frequency and backup time
- **Pause**: Pause the backup task
- **Delete**: Remove the task and all associated snapshots +| **Snapshot now** | Manually trigger a backup immediately | + + +## View snapshot records + +At the bottom of the backup management page, you’ll see a list of snapshots for the backup task, with snapshot information such as: + +- **Creation time**: The execution time of the snapshot. +- **Size**: Size of the snapshot. +- **Status**: The execution status of the snapshot. +- **Backup type**: The snapshot is a full backup or an incremental backup. + + + diff --git a/docs/manual/olares/settings/change-frp.md b/docs/manual/olares/settings/change-frp.md new file mode 100644 index 000000000..f8173a05c --- /dev/null +++ b/docs/manual/olares/settings/change-frp.md @@ -0,0 +1,24 @@ +--- +description: Learn how to change the reverse proxy option in Olares Settings to expose internal services securely. +--- +# Change reverse proxy + +A reverse proxy acts as a secure gateway between your Olares and the open web, enabling you to expose local services to the public internet securely without needing a public IP. For users who do not own a public IP address, Olares offers three reverse options to facilitate external access to Olares applications and services: + +- **Cloudflare Tunnel** – Recommended for most users worldwide. + +- **Olares Tunnel** – Optimized for users in mainland China with different regional IDC options. + +- **Self-built FRP** – Ideal for users with their own FRP servers. + +## Change your reverse proxy option + +1. Open Settings, then navigate to **Network** > **Reverse Proxy**. +2. Choose your preferred reverse proxy option. If you select Self-built FRP, you’ll need to provide the server address, port, and authentication method. + +3. Click **Save** to apply your changes. + +:::warning Change with caution +- Olares sets a default reverse proxy option during installation. Changing this setting may affect connectivity—proceed with caution. +- Switching your reverse proxy between Cloudflare Tunnel and Olares Tunnel will also change your data plan and benefits, as they are separate cloud network services with different pricing and features. +::: diff --git a/docs/manual/olares/settings/custom-app-domain.md b/docs/manual/olares/settings/custom-app-domain.md new file mode 100644 index 000000000..0bc67e3fd --- /dev/null +++ b/docs/manual/olares/settings/custom-app-domain.md @@ -0,0 +1,67 @@ +--- +outline: [2, 3] +description: Customize Olares application URLs with personalized domain names and route IDs. Learn how to set up public access and manage application endpoints. +--- + +# Customize application domains +You can access Olares applications anytime, anywhere, whether you're accessing from local or remotely. This guide will help you: +- Personalize domain name for your applications +- Allow public access without authentication + +## Before you begin +Before you start, it is recommended to familiarize yourself with a few concepts for Olares applications: + +- [Endpoints](../../concepts/network.md#endpoints) +- [Route ID](../../concepts/network.md#route-id) + +## Customize domain name for application + +Olares provides two methods to optimize application access addresses: +* Custom route ID +* Custom domain name + +### Custom route ID +Route ID is a crucial component in accessing your Olares applications. It forms part of the URL you use to reach your applications through a web browser: + +`https://{routeID}.{OlaresDomainName}` + +For convenience, Olares uses easy-to-remember route IDs for pre-installed system applications. +For community applications, you can quickly obtain a simple and memorable URL by changing the route ID. To use Jellyfin as an example: + +1. Open the Settings app, and select **Application** from the left sidebar. +2. Click **Jellyfin** on the right to view application details. +3. Go to **Entrances** > **Set up endpoint**. You can see the default Route ID for Jellyfin, which is a combination of numbers and letters. +4. Next to **Set custom Route ID**, click add. +5. Enter a route ID that is more memorable and recognizable. For example, `jellyfin`. + + ![Custom route ID](/images/manual/olares/custom-route-id.png#bordered) +6. Click **Confirm**. + +Now, you will be able to access Jellyfin from your new URL: `https://jellyfin.bob.olares.com`. + +### Custom domain name +Instead of using the default Olares domain, you can use your own domain name to access your applications, making them more professional and easier to remember. To use Affine as an example: +:::info +Only applications with the authentication level set to **Internal** or **Public** support custom third-party domains. +::: +1. Open the Settings app, and select **Application** from the left sidebar. +2. Click Affine on the right to view application details. +3. Go to **Entrances** > **Set up endpoint**. +4. Next to **Set custom domain**, click add. + + ![Set third-party domain](/images/manual/olares/set-custom-domain.png#bordered) +5. Enter your custom domain, for example, `hello.coffee`, and click **Confirm**. +6. Click **Activation**, and follow the instructions to add a CNAME record on your domain hosting site. Then click **Confirm**. + + ![Activate third-party domain](/images/manual/olares/activate-custom-domain.png#bordered) + At this stage, the custom domain status will display as "Waiting for CNAME Activation". This means you need to wait for the DNS changes to propagate. The propagation time typically ranges from a few minutes to 48 hours, depending on your domain provider. + + Olares will periodically check if the DNS record is correctly configured. Once the CNAME record is verified, the custom domain status will automatically update to "Activated". After activation, you can access Affine using the new URL: `hello.coffee`. +:::tip +To allow public access to your custom domain without login, update the access policies as below: +1. Navigate to **Settings** > **Application**, and click the target application. +2. Click **Entrance**, then under **Create access policies**, set **Authentication level** to **Public**. +3. Click **Submit** to apply changes. + + ![Set auth level to public](/images/manual/olares/set-auth-level-to-public.png){width=50%} +::: diff --git a/docs/manual/olares/settings/developer.md b/docs/manual/olares/settings/developer.md new file mode 100644 index 000000000..7a94ecf53 --- /dev/null +++ b/docs/manual/olares/settings/developer.md @@ -0,0 +1,63 @@ +--- +description: Learn how to manage repositories, view downloaded images, and export system logs for troubleshooting. +--- + +# Developer resources + +The **Developer** page in Olares **Settings** is designed for developers and advanced users to manage core system resources and diagnose issues. Key functions include: + +* **Repository Management** +* **Image Management** +* **Export System Logs** + +## Repository management + +**Repository management** is where you maintain the source repositories for Olares to download essential system images and other software packages. You can view existing repositories, add new ones, and manage endpoints to optimize Olares' package retrieval performance. + +On the repository list page, you can view the name of the repository, number of related images, and image size for each repository. + +![Repo management](/images/manual/olares/repo-management.png#bordered) + +### Add a new repository + +Follow these steps to add a new repository: + +1. Navigate to **Settings** > **Developer** > **Repository management**. +2. Click the **+ Add repository** button in the top-right corner. +3. In the pop-up dialog, fill in the following information: + * **Repository Name**: Enter a unique name for the repository, such as `docker.io` or `quay.io`. + * **Starting endpoint**: Enter the initial URL for the repository. +4. Click **Confirm** to complete the addition. + +### Manage repository endpoints + +You can reorder a repository's access endpoints to optimize its access speed and stability. + +![Endpoint management](/images/manual/olares/repo-endpoint-management.png#bordered) + +1. On the **Repository management** page, click the table_edit button to the right of the target repository. +2. On the **Endpoint management** page, you can: + * **Reorder**: Use the up and down arrows to sort the endpoints. Olares will prioritize the endpoints higher on the list. + * **Delete**: Click the delete button to delete an endpoint you no longer need. + +## Image management + +The **Image Management** page provides a comprehensive view of all downloaded and cached application and software package images on your Olares system. + + +![Image management](/images/manual/olares/image-management.png#bordered) + +## Export system logs + +Logs record the operational status of various system components. When troubleshooting Olares issues, system logs can provide crucial diagnostic information. To download system logs: + +1. Navigate to **Settings** > **Developer** > **Logs**. +2. Click **Collect** to generate the log file. The log will automatically be saved to the `/Home/pod_logs` directory. +3. Click **Open** to open the logs directory in a new window. + + ![Generate logs](/images/manual/olares/export-log.png#bordered) + +4. Right-click the generated log file and select **Download** to save it to your local machine. + + ![Download logs](/images/manual/download-logs.png#bordered){width=70%} +Once downloaded, you can attach the log file to a GitHub feedback post and share it with the Olares team to help them locate the issue faster. \ No newline at end of file diff --git a/docs/manual/olares/settings/gpu-resource.md b/docs/manual/olares/settings/gpu-resource.md new file mode 100644 index 000000000..857667c27 --- /dev/null +++ b/docs/manual/olares/settings/gpu-resource.md @@ -0,0 +1,84 @@ +--- +outline: [2, 3] +description: Manage and optimize GPU resources in Olares with centralized controls, supporting time-slicing, exclusive access, and VRAM-slicing across single or multi-node setups. +--- +# Manage GPU usage +:::info +Only Olares admin can configure GPU usage mode. This ensures optimal resource management across the system and prevents conflicts between users' resource needs. +::: + +Olares allows you to harness the full power of your GPUs to accelerate demanding tasks such as large language models, image and video generation, and gaming. Whether your GPUs are on a single node or spread across multiple nodes, you can manage them conveniently from one centralized interface. + +This guide helps you understand and configure GPU allocation modes to maximize hardware performance. + +::: tip Nvidia GPU only +Currently, only Nvidia GPU is supported. +::: + +## Understand GPU allocation modes + +Olares supports three GPU allocation modes. Choosing the right mode helps optimize performance based on your needs. + +### Time slicing + +In this mode, the GPU's processing power is shared among multiple applications. + +* Acts as a default resource pool. Any application not explicitly assigned to a specific GPU will automatically use a time-slicing GPU if available. + +* Suitable for General-purpose use and running multiple lightweight applications. + +### App exclusive + +In this mode, the entire GPU processing power and memory is dedicated to a single application. + +* Best for intensive, performance-critical applications like AI-generated imagery or high-performance gaming servers. +* Large memory demands may limit availability for other tasks. + +### Memory slicing +In this mode, GPU memory (VRAM) is partitioned into fixed, dedicated amounts for specific applications. + +* Ideal for running multiple GPU-intensive applications simultaneously, each with guaranteed VRAM allocation. +* Prevents memory conflicts between applications running on the same GPU. + +## View GPU status + +To view your GPU status: + +1. Navigate to **Settings > GPU**. The GPU list shows each GPU’s model, associated node, total VRAM, and current GPU mode. +2. Click on a specific GPU to visit its details. + +::: tip Note +If your Olares only contains one GPU, navigating to the GPU section will take you directly to the GPU details page. If you have multiple GPUs, you will see a list first. +::: + +## Configure GPU mode + +On the **GPU details** page, select your desired mode from the **GPU mode** dropdown. Depending on your selected mode, different follow-up options apply. + +* **Time slicing**： + 1. Select this mode from the GPU mode dropdown. + 2. In the **Application pinning** section, click **+Add an application** button to manually pin an application to this specific GPU in a multi-GPU setup. + +:::tip Note +No manual pinning is required if you only have one GPU in your cluster. +::: + +* **App exclusive** + 1. Select this mode from the GPU mode dropdown. + 2. In the **Select exclusive app** dropbox, choose your target application. + 3. Click **Confirm**. + ![App exclusive](/images/manual/olares/gpu-app-exclusive.png#bordered) + +* **Memory slicing** + 1. Select this mode from the dropdown. + 2. In the **Allocate VRAM** section, click **Add application**. + 3. Select your target application and assign it a specific amount of VRAM (in GB). + 4. Repeat for other applications and click **Confirm**. + ![VRAM slicing](/images/manual/olares/gpu-memory-slicing.png#bordered) + + ::: tip Note + You can't assign a VRAM that's larger than the total VRAM. + ::: + +## Learn more +- [Monitor GPU usage in Olares](../resources-usage.md) \ No newline at end of file diff --git a/docs/manual/olares/settings/index.md b/docs/manual/olares/settings/index.md new file mode 100644 index 000000000..8efbad26d --- /dev/null +++ b/docs/manual/olares/settings/index.md @@ -0,0 +1,22 @@ +--- +description: Configure and manage Olares with Settings, your central hub for personalizing your experience, securing your environment, integrating essential services, and more. +--- + +# Configure and manage Olares with Settings + +The Settings application in Olares provides a clean, intuitive interface for configuring and managing your system. It serves as the central hub for personalizing your experience, securing your environment, integrating services, and more. + +Settings is organized into the following sections: + +- Manage security – Manage login devices and system security settings. +- Manage accounts – Create and manage users within your Olares cluster. +- Manage applications – Monitor and configure application status and behavior. +- Manage integrations – Connect Olares to external web services and tools. +- Customize appearance – Set system language and background preferences. +- Configure network – Set up FRP, VPN, and edit the hosts file. +- Backup and restore – Create and manage backup and restore tasks for selected directories. +- Update system – View system details and install updates. +- Export system log – Generate and export system logs for diagnostics. + + + diff --git a/docs/manual/olares/settings/integrations.md b/docs/manual/olares/settings/integrations.md new file mode 100644 index 000000000..64ac37cae --- /dev/null +++ b/docs/manual/olares/settings/integrations.md @@ -0,0 +1,43 @@ +--- +outline: [2, 3] +description: Connect Olares Space and third-party services to enhance functionality. Learn how to integrate, authorize, and manage connected services for seamless data synchronization. +--- + +# Manage integrations in Settings + +The Integration section in **Settings** provides a centralized view of all third-party services connected to your Olares system. It also allows you to manually configure cloud object storage using API credentials. + +OAuth-based integrations and Olares Space must be connected via the LarePass app. See the [Integration guide of LarePass](../../larepass/integrations.md) for details. + + +## View and manage existing integrations + +1. Open **Settings** from the Dock or Launchpad. +2. Go to **Integration** from the left-hand menu. You’ll see a list of currently authorized services. +3. Click an integration card to show its connection status and available actions. +4. In the **Account settings** page, click **Delete** to remove the integration. + +## Add cloud object storage via API keys + +Olares supports manual configuration of AWS S3 and Tencent Cloud COS using API credentials: + +1. Navigate to **Settings** > **Integration** and click the **+ Add Account** button in the top-right corner. +2. Select **AWS S3** or **Tencent COS**, then click **Confirm**. +3. In the mount dialog box, fill in the required details: + - Access Key + - Secret Key + - Region + - Bucket name +4. Click **Next**. You will see a success message if the credentials are valid. + +Your connected cloud storage will now appear under the **Cloud storage** section in Files. + +Alternatively, you can configure this direction directly within [LarePass](../../larepass/integrations.md#add-a-cloud-storage-using-api-keys). + + + + + + + + diff --git a/docs/manual/olares/settings/language-appearance.md b/docs/manual/olares/settings/language-appearance.md new file mode 100644 index 000000000..c061fd6f8 --- /dev/null +++ b/docs/manual/olares/settings/language-appearance.md @@ -0,0 +1,39 @@ +--- +description: Personalize your Olares experience by setting system language preferences, switching between light and dark themes, and customizing desktop and login screen wallpapers. +--- +# Set language and appearance + +Personalizing your Olares experience is easy. You can set your preferred language, choose between light and dark themes, and select custom wallpapers for your desktop and login screen. + +## System language +Olares is currently available in the following languages: +- English +- Chinese (simplified) + +To change your display language: +1. Open the Settings app from the Dock or Launchpad. +2. Select **Appearance** from the left sidebar. +3. Click the dropdown and select your language. + +## Theme +Switch between light and dark themes for system applications. +1. Open the Settings app from the Dock or Launchpad. +2. Select **Appearance** from the left sidebar. +3. In the **Theme** panel, select **Light** or **Dark**. + +The change applies immediately. + +## Wallpaper +To customize your desktop or login screen background: + +1. Open the Settings app from the Dock or Launchpad. +2. Select **Appearance** from the left sidebar. +3. In the **Wallpaper** panel, select where to apply the wallpaper: desktop or login screen. +4. To use a built-in wallpaper, browse and select from the provided images. +5. To add a custom wallpaper: + + a. Click add_photo_alternate and navigate to the target folder on your computer. + + b. Select your desired image file. + + c. Click **Confirm** or **Open** to set it as your wallpaper. \ No newline at end of file diff --git a/docs/manual/olares/settings/manage-entrance.md b/docs/manual/olares/settings/manage-entrance.md new file mode 100644 index 000000000..f3d7886fd --- /dev/null +++ b/docs/manual/olares/settings/manage-entrance.md @@ -0,0 +1,62 @@ +--- +outline: [2, 3] +description: Learn how to manage application entrances in Olares, including setting up endpoints and creating access policies. +--- + +# Manage application entrances + +**Entrances** define how users access your applications on Olares. For a deeper understanding, refer to the [Entrance concept](../../concepts/network.md#entrance) section. + +Entrance management in Olares includes two main components: + +* **Endpoints**: Define the network address and routing configuration for the application. +* **Access policies**: Control the authentication methods required to access the application. + + +## Access entrance management + +To manage an application's entrances: + +1. Go to **Settings** > **Application**. +2. Click on the target application from the list to enter the application page. +3. Click on the target entrance from the list to enter the **Entrances** settings page. +![Manage entrance](/images/manual/olares/app-entrance.png#bordered) + +## Set up endpoints + +The **Set up endpoints** page lets you customize how your application is accessed externally via a dedicated URL. + +Options include: + +- **Endpoint** – The domain for accessing your app. For example,`1870a8290.marvin112.olares.cn` (WordPress). You can click the copy icon to copy the URL. + +**Default route ID** – The system-assigned identifier for the app route. For example, `1870a8290` for WordPress ). + +- **Set custom route ID** – Click the **+** icon to replace the default route ID with a custom one. For example, `1870a8290.marvin112.olares.cn` → `wordpress.marvin112.olares.cn`. + +- **Set custom domain** – Click the **+** icon to bind your own domain (e.g., app.yourdomain.com) to this application. You will need to follow DNS configuration steps to complete the setup. + +For detailed instructions on changing an application's domain, refer to [Customize app domain](custom-app-domain.md). + +## Create access policies + +Access policies control who can access your application and their required authentication method. Options include: + +* **Authentication Level**: Set the overall authentication requirement for the application: + + * **Public**: Accessible to anyone, with no login required. + * **Private**: Requires users to log in to access. + * **Internal**: No login is required if accessing the application via VPN. + +* **Authentication mode**: Specify the method used for verifying user identity: + + * **System**: Inherits the system-wide authentication rules defined on the My Olares page. + * **One Factor**: Requires only the Olares login password. + * **Two Factor**: Requires the Olares login password plus a second verification code. + * **None**: No authentication is required for access. + +* **Sub-policies**: Apply fine-grained access rules to specific paths within the application using **regular expressions**. + + 1. Click the **+ icon** in the **Policies** section. + 2. Define specific rules for desired paths. + 3. Choose the appropriate authentication method for each sub-policy. diff --git a/docs/manual/olares/settings/manage-team.md b/docs/manual/olares/settings/manage-team.md new file mode 100644 index 000000000..f5c805945 --- /dev/null +++ b/docs/manual/olares/settings/manage-team.md @@ -0,0 +1,69 @@ +--- +description: Comprehensive guide to managing teams in Olares, including creating accounts, assigning roles, setting permissions, and maintaining efficient team collaboration within your Olares cluster. +--- +# Manage your team +As an administrator, you can create and manage team members while ensuring optimal system performance through efficient resource controls. +## Before you begin +Ensure that: + +* You have Olares admin privileges +* Your system has sufficient available resources +* Team members have created their Olares IDs + + :::info + When creating a new member account in Olares, make sure the domain part of their Olares ID matches yours. + ::: +## Create a new member + +1. Navigate to the page **Settings** > **Account**. +2. Click **Create account**. +3. In the dialog, fill in the required fields. + - **Olares ID**: Enter the local name only. + - **CPU**: Allocate CPU cores (minimum 1 core) + - **Memory**: Allocate memory (minimum 3GB) +4. Click **Save**. + Once created, you will see activation credentials for the specific Olares ID: + - Activation wizard URL + - One-time password +5. Share activation credentials with the new member. + +You can verify whether they have completed the activation in the **Accounts** page. + +:::tip +New members can activate their account through the wizard without installing Olares locally. +For detailed instructions, see [Activate Olares](../../get-started/activate-olares). +::: + +## Remove a member +:::warning +Ensure users backup important data before deletion - some data cannot be recovered. +::: + +1. Navigate to the page **Settings** > **Account**. +2. Click the member you want to delete to view its account details. +3. Scroll to the bottom, and click **Delete user**. +4. In the dialog, click **OK** to confirm. + +## Manage resource quotas +You can adjust the allocated resources for members in your Olares cluster. + +1. Navigate to the page **Settings** > **Account**. +2. Click the member you need to adjust resource quotas. +3. In the **Account info** page, scroll to the bottom and click **Modify limits**. +4. In the dialog, adjust CPU and memory quotas. +5. Click **OK** to apply changes. + +## Reset passwords +1. Navigate to the page **Settings** > **Account**. +2. Click the member you need to reset password fo. +3. In the **Account info** page, scroll down and click **Reset password**. The new password will be generated immediately. +4. Share the new password with the member. + +## FAQ +### Why can't I create a new user? +If you're an administrator: + +* Ensure the new member has obtained their Olares ID. See [Create an Olares ID](../../get-started/create-olares-id). +* The name you entered is correctly spelled. +* There are sufficient system resources to allocate. + diff --git a/docs/manual/olares/settings/my-olares.md b/docs/manual/olares/settings/my-olares.md new file mode 100644 index 000000000..a636f802e --- /dev/null +++ b/docs/manual/olares/settings/my-olares.md @@ -0,0 +1,47 @@ +--- +outline: [2, 3] +description: Learn how to manage your Olares account, devices, security settings, and network access policies in My Olares. +--- + +# Account and device management + +The **My Olares** page in **Settings** serves as your central hub for managing your Olares account, connected devices, security settings, and access policies. + +To access My Olares, open **Settings** and click your avatar in the top-left corner. + +## Olares Space + +Check your subscribed plan details and usage in Olares Space, including reverse proxy solution, backup storage, and traffic consumption. Log in to Olares Space as prompted to use this feature. + +## Support and feedback + +Access help resources or send feedback to the Olares team regarding your system experience. + +## Change password + +Update your Olares login password to enhance your account security. + +## Set network access policy + +Define system-level access and authentication policies to control how users connect to your Olares. + +* **Network visibility**: Control how visible your Olares services are on the network. Options include: + * **Public**: Services are accessible to anyone on the internet. + * **Protected**: Services are public but require a login for access. + * **Private**: Services are not exposed to the internet and are only accessible via VPN. +* **Login security requirement**: Set the authentication method for logging into Olares. + * **Two-factor** (Recommended): Requires both your login password and a two-factor authentication code for enhanced security. + * **One-factor**: Only requires your login password (less secure). + +## View login history + +Review a detailed record of all login attempts to your Olares account. Each entry displays the **Time**, **Status**, **Source IP Address**, and the **Reason for the attempt**. + +## Device management + +The **Devices** section allows you to view and manage all devices authorized to access your Olares. Each entry provides details about the connected device, such as its name, operating system, connection method, device IP address, and last connection time. + +Available actions are: + +* **View device information**: Click a specific device to view its detailed information such as software type, last active time, location, and token details. +* **Sign out device**: Use this option to remotely disconnect a device from your Olares. The device will need to reauthenticate to access Olares again. diff --git a/docs/manual/olares/settings/remote-access.md b/docs/manual/olares/settings/remote-access.md new file mode 100644 index 000000000..108de388b --- /dev/null +++ b/docs/manual/olares/settings/remote-access.md @@ -0,0 +1,46 @@ +--- +outline: [2,3] +description: Learn how to configure VPN on Olares using Settings, covering VPN enforcement, SSH access, and subnet routing. +--- +# Configure VPN access to Olares + +The [LarePass VPN](../../larepass/private-network.md) provides secure remote access to your Olares device, even when you're on a different network or at a remote location. Olares' Settings app offers advanced configurations to tailor VPN access to your specific needs. Here, you can enforce VPN connections, enable SSH access over VPN, or route traffic through custom ports. + +## Enforce access using VPN + +To ensure that all traffic to your private Olares applications is encrypted and routed securely, you can enforce VPN access. This ensures that connections to your Olares always go through the LarePass VPN, regardless of the network or device used. Enabling this mode will block accesses to Olares via reverse proxy. + +To enable the enforced VPN mode: + +1. Enable VPN connections on at least two devices using LarePass (typically a computer and a mobile phone) with LarePass installed. For detailed instructions, see [Enable VPN on LarePass](/manual/larepass/private-network.md). +2. Open Settings app from the Dock or Launchpad. +3. Click on your profile picture in the top-left corner, and scroll down to **Security** settings. +4. Turn on the switch for **Enforce VPN access to private entrance**. + +When successful, you'll see a confirmation message at the bottom of the screen. + + +## Allow SSH connections via VPN +This enables SSH access to your Olares device through the LarePass VPN, even when you are in a different network or working remotely. + +1. Open the Settings app, and select **System** > **VPN**. +2. Toggle on **Allow SSH Access via VPN**. Port **22** (SSH) is automatically added to the configuration. + + ![SSH via VPN](/images/manual/olares/ssh-via-vpn.png#bordered) +## Allow subnet routing +This feature allows you to access other devices in the same local network as your Olares through the VPN. + +1. Open the Settings app, and select **System** > **VPN**. +2. Toggle on **Enable subnet routes**. + +## Configure ACL rules for port access +After enabling subnet routing, you can further configure ACL (Access Control List) rules to allow traffic to specific ports based on the services you want to access. + +For example, to access a Windows server via Remote Desktop: +1. Click add to open the **Add ACL** dialog. +2. Enter `3389` (default port for Remote Desktop Protocol), and click **Confirm**. +3. Click **Apply** to apply changes. + + ![Add ACL port](/images/manual/olares/add-acl-port.png#bordered) + +Now you can use Windows Remote Desktop to access the Windows server in the same LAN as Olares. \ No newline at end of file diff --git a/docs/manual/olares/settings/restore.md b/docs/manual/olares/settings/restore.md new file mode 100644 index 000000000..e2d94e4bf --- /dev/null +++ b/docs/manual/olares/settings/restore.md @@ -0,0 +1,62 @@ +--- +description: Restore files to a specific directory or recover application data using backup snapshots. Learn how to restore data from local paths, Olares Space, or AWS S3. +--- + +# Restore backup data + +You can use existing backup snapshots to restore files to a specified directory or recover application data. This guide covers how to restore data from local storage, Olares Space, and AWS S3. + +## Add a restore task + +To add a restore task: + +1. Go to **Settings** › **Restore**, then click **Add restore**. +2. Choose a restore method based on your backup location: + + + + + + + +::: tip +If you are restoring from Tencent COS, follow the steps for AWS S3. Refer to [Tencent Cloud documentation](https://cloud.tencent.com/document/product/436/68284) for instructions on how to get the pre-signed URL for your backup files. +::: + +## View restore tasks + +Once created, your restore task will appear in the task list on the Restore page. Click the **›** button on the right to view the task details. Available actions are: + + +- **Cancel restore task** – Click **Cancel** to interrupt and stop the restore process. +- **View files or app** – Once completed, click **Open App** or **Open Folder** to access the restored data. diff --git a/docs/manual/olares/settings/roles-permissions.md b/docs/manual/olares/settings/roles-permissions.md new file mode 100644 index 000000000..6d173d153 --- /dev/null +++ b/docs/manual/olares/settings/roles-permissions.md @@ -0,0 +1,46 @@ +--- +description: Understand Olares team roles and permissions. Learn about administrator responsibilities, user access levels, and effective team management structures. +--- +# User roles and permissions + +Olares supports multi-user operations, allowing multiple users to access the system simultaneously. Each user can securely access resources based on their assigned role and permissions. + +## Role types +Olares has two default user roles: +- **Admin**: Automatically assigned to the first user who activates and logs into Olares +- **Member**: Standard user role with limited permissions + + + + + + + + + + + + + + +
RolePermissions
Member +
    +
  • Use system apps: Files, Vault, Wise, Profile, Dashboard, and Control Hub
    • +
  • Enable VPN for private entrances
    • +
  • Connect to Olares Space
    • +
  • Customize app entrances
    • +
  • Install regular apps in Market
    • +
  • Access shared vaults with assigned read/write permissions
    • +
  • View basic system status in Control Hub
    • +
+
Admin + All Member permissions, plus: +
    +
  • Create and manage user accounts
    • +
  • Manage vault teams, create shared vaults, and assign read/write permissions for shared vaults
    • +
  • Install and manage shared applications
    • +
  • Monitor and manage system resources
    • +
  • Set GPU usage mode
    • +
  • Update Olares
    • +
+
diff --git a/docs/manual/olares/settings/set-up-hosts.md b/docs/manual/olares/settings/set-up-hosts.md new file mode 100644 index 000000000..969a4e939 --- /dev/null +++ b/docs/manual/olares/settings/set-up-hosts.md @@ -0,0 +1,33 @@ +--- +description: Configure and manage your Olares hosts file to customize domain name resolution, map IP addresses, and control access to services with step by step guidance. +--- +# Set up hosts file + +The hosts file is a system configuration file that maps domain names to specific IP addresses. By editing this file, you can customize how Olares resolves domain names, bypass the default DNS resolution, and control access to certain websites or services. +## Add a host +To add a new domain name and IP address mapping in Olares: +1. Open Settings, and go to **System** > **Hosts**. +2. Select **Add hosts** in the top-right corner, and specify the domain name/IP address pair. + - **Host name**: Enter the domain name you want to map (e.g., `example.com`). + - **IP**: Enter the corresponding IP address (e.g., `93.184.216.34`). + ![Add a host](/images/manual/olares/add-host.png#bordered) +3. Click **Confirm** to save the changes. + +:::info DNS cache delay +After editing the hosts file, the changes might not take effect immediately due to DNS caching. +::: + +## Verify hosts file change +To ensure that the new domain-to-IP mapping is working as expected, you can use the `nslookup` command. This command allows you to check whether the domain resolves to the IP address you specified in the hosts file. + +In your command prompt or terminal, run the following command, and replace `[domain-name]` with the domain you want to verify: + ```shell + nslookup [domain-name] + ``` + +The output will include the resolved IP address for the domain. For example: + ```shell + Name: example.com + Address: 93.184.216.34 + ``` +If the `Address` field matches the IP address you configured in the hosts file, it means the changes have taken effect. diff --git a/docs/manual/olares/settings/team.md b/docs/manual/olares/settings/team.md new file mode 100644 index 000000000..6519ead5d --- /dev/null +++ b/docs/manual/olares/settings/team.md @@ -0,0 +1,45 @@ +--- +description: Create collaborative environments in Olares for teams, families, or organizations. Share resources, manage multi-user access, and build customized workspaces efficiently. +--- +# Start a team +Do you want to share Olares with your family, friends, or coworkers? Here's everything you need to know about creating a collaborative Olares environment. + +## Why Olares for teams +Olares's multi-user design efficiently shares system resources, eliminating redundant deployments that would otherwise increase with each new user. + +When you share Olares with others, you can: +* Create a powerful workspace using professional-grade open source alternatives without subscription fees. +* Enable everyone to access resource-intensive AI applications without system overhead. +* Build a central hub for shared files, photos, and documents with secure access from anywhere. +* Store and manage shared files, photos, and documents. + +Transform your system into the hub that best serves your group - a smart home control center, a workspace, or a media server. With the rich applications in Olares, you can customize the environment to match how your team wants to work and collaborate. + +## The Olares cluster +Your Olares installation creates a Kubernetes-based environment that efficiently supports multiple users while minimizing system overhead. Think of your Olares installation as a digital home for your team. When you set it up, your device becomes a private server that everyone can access securely. + +## Your role as administrator +As an Olares administrator, you'll mainly be responsible for: + +* Managing user accounts for team members +* Installing and maintaining system-wide applications that everyone shares +* Ensuring fair resource allocation across the system + +--- + +
+

User roles and permissions

+Understand different roles in Olares. +
+ +
+

Manage your team

+Set up accounts for your team members. +
+ +
+

Collaborate in Olares

+Learn how to invite and interact with team members. +
+ + diff --git a/docs/manual/olares/settings/update.md b/docs/manual/olares/settings/update.md new file mode 100644 index 000000000..091279dde --- /dev/null +++ b/docs/manual/olares/settings/update.md @@ -0,0 +1,41 @@ +--- +description: Learn how to safely update your Olares system, check for new versions, install system updates, and manually update olaresd for optimal performance and security. +--- +# Update Olares + +Olares regularly releases new versions with feature improvements and usability enhancements. This guide explains how to check for and install system updates. + +:::info Olares admin required +Only Olares admin can perform system updates. Updates will apply to all members within the same Olares cluster. +::: + +:::tip +For details on Olares versioning practices and the current limitations regarding cross-minor version upgrades (e.g. `1.10.5` to `1.11.0`), see [Olares versioning](/developer/install/versioning.md). +::: + +## Check and install updates +:::tip +Review the release notes before updating to learn about new features and important changes. +::: + +1. Open Settings, and click **System** > **My Olares** > Current version. +2. Click **Upgrade now** when there is an available new version. + +You'll see a confirmation message when update completed. + +## Update `olaresd` manually + +`olaresd` is the core daemon process of the Olares system responsible for various key management functions. In some cases, after your update Olares via the Settings app, a manual update of `olaresd` may be required to resolve issues where certain services fail to operate correctly. + +To confirm if this step is required, refer to the [Release notes](https://github.com/beclab/Olares/releases/). + +To update `olaresd` manually: + +1. Open Control Hub, and navigate to **Terminal** > **Olares**. + ![Open terminal in Olares](/images/manual/olares/olares-terminal-in-control-hub.png#bordered) +2. Execute the following command in the terminal: + ```bash + curl -SsfL https://dc3p1870nn3cj.cloudfront.net/upgrade_1_11_6.sh | bash - + ``` + where: + - `1_11_6` means to upgrade `olaresd` and `olares-cli` to version `1.11.6`. \ No newline at end of file diff --git a/docs/manual/olares/vault/index.md b/docs/manual/olares/vault/index.md new file mode 100644 index 000000000..258e8f840 --- /dev/null +++ b/docs/manual/olares/vault/index.md @@ -0,0 +1,42 @@ +--- +description: Secure your sensitive data with Vault - a comprehensive password manager featuring end-to-end encryption, shared vaults, cross-device sync, autofill, and two-factor authentication support. +--- +# Secure sensitive data with Vault + +Vault is a password manager in Olares, designed for secure storage and management of sensitive data. With Vault, you can safely store and organize private keys and passwords, digital identities (DIDs) and Olares IDs, one-time passwords (OTPs), and other confidential data. + +Key features of Vault include: +* End-to-end encryption for maximum security +* Private and shared vaults for personal and organizational use +* Seamless synchronization across devices +* Autofill functionality for easy credential input +* Strong password suggestions for enhanced account security +* Two-factor authentication (2FA) support with OTP management + +## Clients +Vault's server component runs on Olares, synchronizing data across multiple client devices of a single user. Data is encrypted with a private key during transmission and storage to ensure security. +You can access Vault in Olares, or through LarePass on mobile, desktop, and browser extensions for a consistent user experience across platforms. + +Visit the [official page](https://olares.com/larepass) for LarePass details and download options. + +--- +
+

Vault basics

+Understand vault items, and learn how to securely store and manage your sensitive data in Vault. +
+ +
+

Share vault items

+Learn how to manage team vault access, and work with shared vaults. +
+ +
+

Set up two-factor authentication codes

+Learn how to generate and store 2FA codes for enhanced security. +
+ +
+

Use autofill with LarePass

+Learn how to set up and use autofill for logins with different LarePass clients. +
+ diff --git a/docs/manual/olares/vault/share-vault-items.md b/docs/manual/olares/vault/share-vault-items.md new file mode 100644 index 000000000..bffe8208a --- /dev/null +++ b/docs/manual/olares/vault/share-vault-items.md @@ -0,0 +1,69 @@ +--- +outline: [2, 3] +description: Learn how to share vault items securely in Olares, manage team access permissions, create shared vaults, and efficiently collaborate while maintaining data security. +--- + +# Share vault items +A shared vault is an effective method for organizing, managing, and securely sharing data among users within the same Olares cluster. Whether you're managing family accounts or enterprise-level data, Team Vault provides the perfect balance of security and collaboration. + +## Understand team roles +:::info +The Olares admin automatically becomes the shared vault owner. +::: +| Role | Owner | Administrator | Member | +|----------------------------------|-------|---------------|--------| +| Add, suspend, reactivate members | ✅ | ✖️ | ✖️ | +| Appoint administrators | ✅ | ✖️ | ✖️ | +| Create shared Vault items | ✅ | ✅️ | ✖️ | +| Assign read/write permissions | ✅ | ✅ | ✖️ | + +## Get started with team access +### Confirm membership +All administrators and users of an Olares cluster are automatically included in one vault team. However, for security reasons, each new member must be verified before accessing team vault items. + +1. In Vault, navigate to the page **My Team** > **Invites**. +2. Click on the member's account name to view the invitation code. + + ![Invite members](/images/manual/olares/invite-members.png#bordered) +3. Send the invitation code to the corresponding member. + :::tip + For members, navigate to the page **Invites** > **My team** in Vault to accept invitation. + ::: +4. After the member confirms the invitation, return to the invitation page and click **Add member**. + +### Set administrator +1. In Vault, navigate to the page **My team** > **Members**. +2. Select a member from the member list. +3. Click more_horiz in the top right corner, and select **Make admin**. +4. To remove administrator privileges, select **Remove member**. + +### Suspend members +1. In Vault, navigate to the page **My team** > **Members**. +2. Select a member from the member list. +3. Click more_horiz in the top right corner, and select **Suspend**. +4. To reactivate a member, select **Unsuspend**. + +:::info +Suspended members retain their role but won't receive updates or make changes. Reactivation requires reverification for security. +::: + +## Work with shared vaults +Shared vaults are designed for sharing data among multiple Olares users. By default, they must be created by Olares admin. +### Create a shared vault +1. In Vault, navigate to the page **My team** > **Vaults**. +2. Click add in the top right corner, and enter vault name. +3. Click **Save**. + +### Edit shared vault permissions +1. In Vault, navigate to the page **My team** > **Vaults**. +2. Select the shared vault to edit permissions. You can add or remove members and set read/write permissions. +3. Click **Save**. + +### Delete a shared vault +:::warning +Deleting a shared vault permanently removes all associated data. Always double-check before confirming deletion. +::: +1. In Vault, navigate to the page **My team** > **Vaults**. +2. Select the shared vault to view vault details. +3. Click more_horiz in the top right corner, and select **Delete**. +4. In the popup dialog, enter `DELETE` to confirm deletion. diff --git a/docs/manual/olares/vault/vault-items.md b/docs/manual/olares/vault/vault-items.md new file mode 100644 index 000000000..8ff1a3d0a --- /dev/null +++ b/docs/manual/olares/vault/vault-items.md @@ -0,0 +1,155 @@ +--- +outline: [2, 3] +description: Understand Vault basics in Olares. Learn to set up vaults, manage vault items, organize sensitive data with tags, and protect your information with local passwords and encryption. +--- + +# Vault basics +This guide will walk you through the fundamentals of using Vault, from setting up your first vault to organizing your sensitive data efficiently. + +## Understand Vault components + +### Types of vault +Olares Vault offers two main types of vaults for users: + +* Main vault (**My vault**): Automatically created upon account activation, serving as the user's private vault. It's encrypted with the user's mnemonic for maximum security. +* Shared vault (**Team vault**): These are collaborative vaults within Olares, allowing secure information sharing among team members or family. + +### Vault items +Think of vault items as individual secure containers for your sensitive information. Each vault item consists of several components: + +* **Name**: A title for easy identification +* **Tags**: For organization and quick filtering +* **Fields**: Various data types to store different kinds of information +* **History**: Tracks changes made to the item +* **Attachments**: For adding related files +* **Expiration**: Set an expiry date for time-sensitive information + +Currently, Vault supports various default types for a vault item: +- Website/App +- Computer +- Credit card +- Bank account +- Wi-Fi Password +- Passport +- Authenticator +- Document + +### Fields +Fields are the core component of Vault Items, allowing storage of various data types, including: + +* Username +* Password +* Mnemonic +* Email address +* URL +* Date and month +* Credit card number +* Phone number +* PIN +* Plain text +* One-time password (OTP) + +## Protect Vault with password +When use Vault in Olares for the first time, you will be prompted to set a local password. This password should not be the same as your Olares login password. + +1. Set the local password for Vault. +2. Import the Olares ID that's already linked to your Olares server using mnemonic phrase. + +![Vault password](/images/manual/olares/vault-local-password.png) + +:::info +If you don't know where to find the mnemonic phrase, see [back up mnemonic phrase](/manual/larepass/back-up-mnemonics). + + +## Manage vault items +:::tip +Keep your vault organized from the start by using descriptive names and relevant tags. This becomes especially valuable as your collection of secure items grows. +::: + +### Add +To add a vault item: + + + + + + + +### Edit +:::info +The LarePass browser extension does not support editing vault items. For full editing capabilities, please use the Vault app in Olares, the mobile, or desktop versions of LarePass. +::: +In the edit mode, you can: +- Update required fields. +- Add tags to items for easy organization and filtering. +- Set an expiration time. +- Add file attachments. Each file must not exceed 1 MB. +- View and restore a history item. Vault keeps up to 10 records for each item. When this limit is reached, older entries are discarded to make way for new ones. + +To edit a vault item: +1. In Vault, select the vault item you need to edit. +2. In its details window or page, click edit_note in the top right corner to enter edit mode. +3. Make the necessary changes to the item's details. +4. Click **Save**. + +### Favorite +Important items can be marked as favorites for quick access. + + + + + + + +## Filter vault items +You can use quick filters or search box to locate the vault item you need. +### Quick filters +* By Main Vault & Shared Vault: Select **My Vault** or **Team Vault** to quickly find items within. +* By Tags: Click on tag names to locate tagged vault items easily. +* By Favorites: Click on **Favorites** to list all your favorite items. +* By Recently Used: Click on **Recently used** to display your recent items. +* By attachment: Click on **Attachment** to display all items with attached files. + +### Keyword search +Click search to directly search for target items using keywords. \ No newline at end of file diff --git a/docs/manual/olares/view-database-status.md b/docs/manual/olares/view-database-status.md new file mode 100644 index 000000000..8d7543414 --- /dev/null +++ b/docs/manual/olares/view-database-status.md @@ -0,0 +1,57 @@ +--- +description: Access and monitor your Olares database status using Bytebase, managing PostgreSQL and MongoDB instances with detailed configuration guidance. +--- +# View database status in Olares +You can use third-party applications to view database status in Olares. + +For example, Bytebase is a multipurpose middleware for working with databases. This guide uses Bytebase to demonstrate how to access database in the middleware. + +## Before you begin +Make sure that you have installed Bytebase from Market. + +![bytebase](/images/how-to/olares/controlhub/middleware/07.jpg#bordered) + +## Add a PostgreSQL instance + +To add a PostgreSQL instance in Bytebase: + +1. In **Bytebase**, click **Add Instance**, and select **PostgreSQL**. +2. Configure the instance: + - **Instance Name**: `Olares` or others. + - **Environment**: Choose either `PROD` or `TEST`. + - **HOST**, **USERNAME**, **PASSWORD**: Fill according to the information in the Control Hub's **Middleware** section. + + ![alt text](/images/how-to/olares/controlhub/middleware/09.jpg#bordered) + +3. Click **Create** to save the changes and connect the instance. + +Now you should be able to view the details of the PostgreSQL instance you just added. + +![alt text](/images/how-to/olares/controlhub/middleware/10.jpg#bordered) + +## Add a MongoDB instance +To add a MongoDB instance in Bytebase: + +1. In **Bytebase**, click **Add Instance**, and select **MongoDB**. +2. Configure the instance. + - **Instance Name**: `Olares` or others. + :::info NOTE + Do not use duplicate instance names. + ::: + - **Environment**: Choose either `PROD` or `TEST`. + - **HOST**, **USERNAME**, **PASSWORD**: Fill according to the information in the Control Hub's **Middleware** section. + + ![bytebase1](/images/how-to/olares/controlhub/middleware/11.jpg#bordered) + +3. Click **Create** to save and connect the instance. + +Now you should be able to view the details of the MongoDB instance you just added. + +![alt text](/images/how-to/olares/controlhub/middleware/12.jpg#bordered) + +## Edit the database + +In Bytebase, click **SQL Editor** in the upper right corner to go to the **Editor** page for further operations. + +![bytebase1](/images/how-to/olares/controlhub/middleware/13.jpg#bordered) + diff --git a/docs/manual/olares/wise/basics.md b/docs/manual/olares/wise/basics.md new file mode 100644 index 000000000..62e7f480e --- /dev/null +++ b/docs/manual/olares/wise/basics.md @@ -0,0 +1,86 @@ +--- +outline: [2, 3] +description: Get started with Wise in Olares. Learn to collect content, organize your reading library, add notes, track progress, and customize your reading experience. +--- +# Wise basics + +Wise helps you curate and organize your reading materials with flexible options for collecting, reading, and managing content. This page covers the essential tasks to get you started with Wise. + +## Add content to your library +Save interesting content using any of these methods. + +### Add to Inbox or Read Later +Organize your reading flow with two collections: + +* **Inbox**: Your primary collection for content you want to read soon. +* **Read Later**: Your backlog for content to revisit in the future. + +While browsing the title or reading, click **inbox Inbox** or **schedule Read Later** to save content to either collection. + +![Inbox or Read later](/images/manual/olares/inbox-read-later.png#bordered) + +### Manually add content +Wise supports various content types including videos, audio, PDFs, and eBooks: + +1. Click add_circle in the menu bar. +2. To add a web page, select **Web page**. +3. To add a downloadable link, select **Download link**. +4. To add a PDF or E-book (in EPUB format) from your local machine, select **Upload**. +5. To add an RSS feed, select **RSS**. + :::tip + To explore how you can leverage RSS subscription with Wise, see [Subscribe to an RSS feed](./subscribe). + ::: + +## Automatic download +Wise automatically creates download tasks for new audio or video content, saving media files to Olares for convenient offline access. + +This feature: + +* Ensures your content is always available offline +* Prevents content loss if the original source becomes unavailable +* Provides quick access to your media files + +To view all your downloaded media files, go to settings > **Transmission** > **Download**. This page shows a complete list of your downloads along with their details. +![Downloaded media files](/images/manual/olares/downloaded-media-files.png#bordered) + +You can click folder_open to locate the target content in the Files app. + +## Organize your reading + +### Use tags for organization +To create a structured content collection with tags: + +1. On the list page, click sell on the content card. +2. In the tag input box, select or create tags relevant to the current content. + +![Tags](/images/manual/olares/tags.png#bordered) + +You can find and manage your tags in the page settings > **Tags**. + +### Capture insights with notes +1. While reading, click right_panel_open to open the **Info** panel. +2. Add your thoughts in the **Note** section. +3. Click **Save** to store your notes. + +You can edit or delete note later. + +![Notes](/images/manual/olares/notes.png#bordered) + +### Track your reading progress +Wise uses green dot indicators on article covers to help you track unread content. When you open an article, it's automatically marked as read. + +While reading, you can manually toggle between **playlist_add_checkSeen** or **playlist_removeUnseen** status in the toolbar to maintain your reading progress. + +### Search from Wise + + +## Change appearance +By default, Wise follows your system's light/dark theme settings. You can override this to set your preferred appearance: + +1. Click the settings in the bottom left corner and select **Preferences**。 +2. Under **Theme**, choose your preferred appearance: + - Light mode + - Dark mode + +## Learn more +- [Build your knowledge hub with Wise](../../best-practices/organize-content.md) \ No newline at end of file diff --git a/docs/manual/olares/wise/filter-examples.md b/docs/manual/olares/wise/filter-examples.md new file mode 100644 index 000000000..689bb130f --- /dev/null +++ b/docs/manual/olares/wise/filter-examples.md @@ -0,0 +1,56 @@ +--- +description: Learn how to use advanced filters in Wise to organize, prioritize, and rediscover your saved content. These examples cover practical use cases like focusing on unread entries and revisiting old content. +--- + +# Filtered view examples +This guide provides examples of filter queries for Wise. Each example addresses a specific use case, making it easy to organize, sort, and rediscover content in your library. + +## Focus on unread entries from a specific feed +Want to catch up on just one feed? Use this query to display all unread entries from a particular source. +``` +feed_id:12345 AND seen:false +``` + +## See everything by your favorite author +Easily pull up all entries written by a specific author you love. +``` +author:"John Doe" +``` +This shows all documents where the author is "John Doe" so you can stay up-to-date with a writer's work. + +## Stay up-to-date with the latest content +Only want to see new articles? Filter for content published after a specific date. +``` +published_at__gt:2025-04-01 +``` +This query displays entries published after April 1, 2025. It's a great way to focus on fresh updates and avoid getting lost in older material. + +## Review saved content with notes +Use this query to find tagged entries that include your own notes: +``` +tag:AI AND has:note +``` +This is useful for revisiting saved content where you've added personal insights or comments. + +## Prioritize tagged "Read Later" entries +Need to focus on specific topics? This filter shows all your "Read Later" entries with a particular tag. +``` +tag:Work AND location:readlater +``` +This pulls up all entries tagged with "Work" that are saved to your "Read Later" list. It's perfect for tackling important projects or topics you've set aside. + +## Clean up your inbox with unread videos +Want to catch up on videos from your RSS feeds? This filter focuses on unwatched content. + +``` +file_type:video AND seen:false AND isfeed:true +``` +This shows all unread video entries from your subscribed feeds. It's ideal for binge-watching or sorting through your video backlog. + +## Revisit entries you haven't opened in months +Got old productivity-related entries that you haven't touched in a while? This filter helps you rediscover them. + +``` +last_opened__lt:2023-12-31 AND tag:Productivity +``` +This shows all entries that you last opened before December 31, 2023. You can revisit useful content you've saved for productivity but might have forgotten about—or decide if it's time to delete it. \ No newline at end of file diff --git a/docs/manual/olares/wise/filter-syntax-guide.md b/docs/manual/olares/wise/filter-syntax-guide.md new file mode 100644 index 000000000..049a10e94 --- /dev/null +++ b/docs/manual/olares/wise/filter-syntax-guide.md @@ -0,0 +1,145 @@ +--- +outline: [2,4] +description: Explain key syntax rules and available filters in Wise. +--- +# Filter syntax reference + +Filtered views are powerful tools for organizing your entries. You can customize your queries using various parameters and operators. Here's a breakdown of the key syntax rules and available filters. + +## Query structure +To create a query with a single condition, simply specify the parameter and its value. + +**Example**: +``` +feed_id:12345 +``` + +You can also combine multiple parameters using logical operators. + +### `AND` +Use `AND` to link parameters that must *all apply* to the results. + +**Example**: + +Retrieve entries that are unread *and* marked as "Read later": +``` +location:readlater AND seen:false +``` + +### `OR` +Use `OR` to link parameters where *at least one* condition must apply. + +**Example**: + +Retrieve entries that are from the library *or* the last opened date is earlier than January 1, 2023: +``` +islibrary:true OR last_opened__lt:2023-01-01 +``` + +### Group with parentheses +You can use parentheses (`()`) to group conditions and control the order of evaluation in your queries. + +**Example**: + +Retrieve entries that are unread *and* either in the inbox *or* marked as "Read Later": +``` +seen:false AND (location:inbox OR location:readlater) +``` + +### Special characters +If a filter condition contains special characters (such as spaces, colons, etc.), enclose it in double quotes `""` (excluding the double quotes themselves). For example: +``` +tag:"Project/AI" +``` +``` +author:"Arthur C. Clarke" +``` +## Parameters + +### Basic parameters +Use the format `parameter:value` to filter entries based on specific conditions. + +#### `feed_id` +Feed ID the entry belongs to. +You can find the Feed ID in the settings > **RSS feeds** page. + +#### `author` +Author of the entry. + +#### `file_type` +The file type of the entry. +Valid file types are: +- `article` +- `video` +- `audio` +- `ebook` +- `pdf` + +### Time parameters +Filter entries based on time-related fields using the format `parameter__operator:value`. Dates must be specified in absolute format: `YYYY-MM-DD`. + +#### `published_at` +Publication time of the entry. + +#### `created_at` +Creation time of the entry. + +#### `updated_at` +Last updated time of the entry. + +#### `last_opened` +Last time the entry was opened. + +#### Operators +Available operations are: +- `__gt` (Greater than)
+ Retrieve entries where the time is **after** the specified date. + +- `__gte` (Greater than or equal to)
+ Retrieve entries where the time is **on or after** the specified date. + +- `__lt` (Less than)
+ Retrieve entries where the time is **before** the specified date. + +- `__lte` (Less than or equal to)
+ Retrieve entries where the time is **on or before** the specified date. + +### Boolean parameters +Filter entries based on true/false values using the format `field_name:true/false`. + +#### `islibrary` +Whether the entry is from a "library" source. + +#### `isfeed` +Whether the entry is from a "feed" source. + +#### `seen` +Whether the entry has been read. + +### Location parameters +Filter entries based on their location. + +#### `location` +Indicates the location of the entry. + +Available values are: +- `all`: All entries. +- `readlater`: Entries marked as "Read Later". +- `inbox`: Entries in the inbox. + +### Related content parameters +Filter entries based on whether they have specific related content. + +#### `has` +Use the `has` parameter to filter entries by the presence of specific content. + +Available values are: +- `note`: Whether the entry has notes. +- `tag`: Whether the entry has tags. + +#### `tag` +Filter entries by the name of a specific tag. + +#### `tag_id` +Filter entries by the unique ID of a specific tag. +You can find the Feed ID in the settings > **Tags** page. \ No newline at end of file diff --git a/docs/manual/olares/wise/filter.md b/docs/manual/olares/wise/filter.md new file mode 100644 index 000000000..5e59af366 --- /dev/null +++ b/docs/manual/olares/wise/filter.md @@ -0,0 +1,58 @@ +--- +description: Learn how to use Wise powerful filtering system to organize your library. Create tag-based views, add custom filtered views, and utilize advanced query parameters to manage your content effectively. +--- +# Organize your knowledge with filters + +As your Wise library grows, staying organized can become challenging. With filtered views, you can easily sort and access content by applying filters based on parameters like tags, saved dates, authors, and more. + +This guide covers how to: +- Create filtered views from tags and subscribed feeds. +- Add custom filtered views using queries. + +:::info +Only entries from feeds or entries saved to **inbox Inbox** or **schedule Read Later** can be queried. +::: + +## Use tags or feeds to filter entries +Filtered views allow you to organize your content by grouping entries based on tags or feeds. This helps you quickly access content related to specific topics or sources. + +1. Open Wise, click settings in the bottom left corner. +2. Depending on your preference: + - Select **Tags** to filter content by specific topics or categories. + - Select **RSS feeds** to filter content from specific sources. +3. For existing tags, click **Manage views...**. You can: + - Group content from the tag or feed into an existing view, or + - Create a new view to group all related content. + + ![Filter entries from feeds](/images/manual/olares/filter-entries-from-feed.png#bordered) +4. If creating a new view: + - Enter a name for the view (e.g., `Tech Articles`). + - Click **Confirm** to save the view. + +## Add custom filter view +For more flexibility, you can create custom filtered views using query language. This allows you to define precise conditions for grouping content. + +The following demonstrates how to create a view for the tag "AI" using query language: + +1. Open Wise, click settings in the bottom left corner and select **Filtered views**. +2. In the top-right corner, select **Add view**. +3. Enter a name for the view (e.g., "AI trends"), and enter `tag:AI` in the **Query** filed. +4. Click **Confirm** to save this view. + + ![Add filtered view](/images/manual/olares/add-filtered-view.png#bordered){width=70%} + +## Pin views to sidebar +You can pin filtered views to the sidebar using either of these methods: + +- Locate the view in the list and click keep in the corresponding **Operations** column. +- Open the filtered view, click keyboard_arrow_down in the header, and select **Pin to sidebar**. + + ![Pin to sidebar](/images/manual/olares/pin-to-sidebar.png#bordered){width=50%} +## Available filters +To explore all available filtering options and learn how to use them, refer to the following: + +- [Filtered view examples](filter-examples) +- [Filter syntax reference](filter-syntax-guide.md) + + + diff --git a/docs/manual/olares/wise/index.md b/docs/manual/olares/wise/index.md new file mode 100644 index 000000000..bdb4c30df --- /dev/null +++ b/docs/manual/olares/wise/index.md @@ -0,0 +1,33 @@ +--- +description: Transform your Olares into a powerful information hub with Wise - featuring AI-driven content curation, cross-platform aggregation, and seamless bookmarking capabilities. +--- +# Curate information hub with Wise + +Wise is a local-first, AI-driven modern reader and a core application within the Olares ecosystem. Working together with the LarePass Chrome extension, Wise assists you in collecting, consuming, and managing content from various platforms, thereby creating and maintaining a personal information hub. + +Key features include: + +* **Self-hosted recommendation algorithms**: You can run personalized algorithms to filter and sort online content, breaking through the information bubble and receiving diverse and personalized content recommendations. +* **Cross-platform content aggregation**: Wise integrates articles, videos, audio, and feeds from different sources, offering you a comprehensive experience. +* **Seamless bookmarking**: With the LarePass browser extension, you can save web pages to Olares with a single click, making it easy to access and manage content anytime. + +--- +
+

Wise basics

+Learn the essential tasks for collecting, reading, and managing your content library in Wise. +
+ +
+

Discover themed content

+Learn how self-hosted recommendation algorithms work in Wise. +
+ +
+

Subscribe and manage feeds

+Set up and organize your content sources through RSS feeds, manual subscriptions, and the LarePass browser extension. +
+ +
+

Add filtered view

+Learn how to use advanced filters to organize and display content based on specific criteria like tags, authors, or publication dates. +
\ No newline at end of file diff --git a/docs/manual/olares/wise/recommend.md b/docs/manual/olares/wise/recommend.md new file mode 100644 index 000000000..955688ca5 --- /dev/null +++ b/docs/manual/olares/wise/recommend.md @@ -0,0 +1,53 @@ +--- +description: Discover how you can use Wise to implement self-hosted recommendation algorithms, deliver personalized content, and maintain both your privacy and control over content discovery in Olares. +--- +# Discover themed content +Most digital platforms control what content you see through centralized recommendation systems that collect and analyze your data. Wise offers a different approach - you choose and run recommendation algorithms directly on your device, keeping your reading preferences and interactions completely private while still enjoying personalized content discovery. +## How self-hosted recommendation works +Content recommendation in Wise happens in two distinct stages: + +1. Content providers collect and package global content in the cloud. +2. Your Olares device downloads this content and processes it locally using your chosen recommendation algorithms. + +Since every device receives the same content data and processes recommendations offline, your reading preferences and interaction data remain completely private. You can monitor these recommendation workflows through a visual interface that shows exactly how your content is being processed. + +As you continue to read and bookmark content in Wise, the algorithm learns your preferences and improves its recommendation accuracy over time. + +## Install a recommendation algorithm +To start receiving personalized content recommendations: + +1. In Market, browse the **Recommendation** category for a topic that interests you. +2. Click **Get** to install your chosen algorithm. +3. Allow some time for the algorithm to complete its local recommendation workflow. + + ![Recommendation algorithm](/images/manual/olares/install-recommendation.png#bordered) + +Once installed, find your recommended content on the **For you** page in Wise. This page displays results from all your installed recommendation algorithms, with separate content feeds for each. Switch between different algorithms by clicking the recommendation title at the top. + +![For you](/images/manual/olares/for-you.png#bordered) + +:::tip +You can subscribe to a feed to read all content from that source in the future. +::: + +## Monitor algorithm workflow +To track how your recommendation engine processes data and generates suggestions: + +1. In the left menu bar, click settings, and select **Recommendations**. +2. Click any specific workflow to view its operation records. +3. Click a record to see detailed information and logs. + +![Recommendation algorithm workflow](/images/manual/olares/recommendation-algorithm-workflow.png#bordered) + +The workflow visualization shows each step of the recommendation process. You can examine step summaries, container settings, and operation logs for complete transparency. + +## Remove a recommendation algorithm +To uninstall a recommendation algorithm: + +1. In Market, go to the page **My Olares**. +2. Click keyboard_arrow_down next to the application's operation button, and select **Uninstall**. + +## FAQ + +### Why can't I see recommended content after installation? +If you've just installed a recommendation algorithm, you'll need to wait briefly while it completes the local recommendation workflow on your Olares. This ensures all processing happens locally to protect your privacy. \ No newline at end of file diff --git a/docs/manual/olares/wise/subscribe.md b/docs/manual/olares/wise/subscribe.md new file mode 100644 index 000000000..33a1ce3e9 --- /dev/null +++ b/docs/manual/olares/wise/subscribe.md @@ -0,0 +1,82 @@ +--- +outline: [2, 3] +description: Learn how to manage content subscriptions in Olares, including adding RSS feeds, importing OPML files, managing subscriptions with LarePass, and organizing your content sources efficiently. +--- + +# Subscribe and manage feeds +Wise offers flexible subscription options to help you follow your favorite content sources, including articles, blogs, podcasts, and video channels. This guide explains how to add and manage your subscriptions. + +## Subscribe methods +:::tip +When you subscribe to podcast or video channels in Wise, new episodes automatically download to your Olares storage. This ensures your media content is always available—even offline—and protected from source deletion or unavailability. +::: + +### Add subscriptions from For you +When browsing recommended content on the **For you** page, you can subscribe to content sources using the following options: + +* Click **Subscribe this Feed** in the **Info** column +* Click bookmark_add in the toolbar + +### Add RSS feeds manually +1. Open the RSS feed dialog with either option: + * Click add_circle on the bottom left, and select **RSS feed**. + * Click settings on the bottom left, select **RSS feeds**, then click **Add feed** in the top right corner. +2. In the dialog, enter the feed information using any of these formats: + * Feed name. For example, `techcrunch`. + * Website URL for RSS feed search. + * Direct RSS link. +3. Click **Add** to complete the subscription. + +### Import RSS feeds from OPML +OPML files allow you to easily import RSS feed collections from other users or RSS readers. This is a convenient way to migrate your existing feed subscriptions or add curated feed collections. + +1. Click settings in the bottom left corner and select **Preferences**. +2. Under **Import/Export**, click **Import feeds from OPML file**. +3. Select your OPML file and open it. + +After import, you can view and manage your RSS feeds under settings > **RSS feeds**. + +:::info + Only new feed subscriptions will be imported. Historical feed content from your previous reader won't be transferred. +::: +### Use LarePass for web subscriptions +:::tip +LarePass extension is currently available for Chrome browsers only. Download it from the [official page](https://olares.com/larepass). +::: +1. Open the LarePass browser extension, and click **Collect**. +2. For the current webpage, check available subscriptions in the **RSS** section. + :::info + The **RSS** option appears only when feeds are detected on the current page. + ::: +3. Click bookmark_add to add the feed to Wise. + +:::tip Upload cookie + +Some websites require cookies for accessing content: +1. Log in to the target website. +2. Open the LarePass browser extension, and click **Collect** > **Cookie**. +3. Click **Upload** to apply changes or enable **Auto Sync**. + +You can hover over cookies to view details. +::: +## View subscription list +Access all your RSS feed subscriptions from settings > **RSS feeds**. + +You can: + +* View feed details and descriptions +* Search for specific feeds +* Copy RSS links +* Edit feed names and descriptions + +## Unsubscribe +:::warning +Unsubscribing removes all articles from this feed unless they're saved to your Library. This action cannot be undone. +::: + +You can unsubscribe from content sources in several ways: + +* From the **Info** column +* Through the reading page toolbar +* Via the LarePass browser extension +* On the **RSS Feeds management** page \ No newline at end of file diff --git a/docs/manual/release-notes.md b/docs/manual/release-notes.md new file mode 100644 index 000000000..c5443e323 --- /dev/null +++ b/docs/manual/release-notes.md @@ -0,0 +1,3 @@ +# Release notes + +Text diff --git a/docs/manual/system-architecture.md b/docs/manual/system-architecture.md new file mode 100644 index 000000000..4a07c3ff0 --- /dev/null +++ b/docs/manual/system-architecture.md @@ -0,0 +1,220 @@ +--- +outline: [2, 3] +description: Comprehensive guide to Olares architecture covering infrastructure, platform services, and application framework. Learn about container orchestration, storage, networking, and system components. +--- + +# Olares architecture + +This document provides a comprehensive explanation of the Olares architecture, outlining the purpose and functionality of each layer and its components. + +![Olares architecture diagram](/images/manual/architecture-diagram.png) + +## Infrastructure + +The infrastructure layer provides essential infrastructure services such as container orchestration, storage, networking, and cluster management. + +### Container orchestration + +Olares supports different Kubernetes distributions depending on the underlying environment: +- Linux environments (including WSL, PVE, LXC, Raspberry Pi): Users can choose to install [Kubernetes](https://kubernetes.io/) or the lightweight [K3s](https://k3s.io/), with K3s being the default for its better performance and resource efficiency on local hardware. +- macOS: [minikube](https://minikube.sigs.k8s.io/) is used to deploy Kubernetes within a Linux virtual machine, ensuring a unified experience across platforms. + +Regardless of the chosen Kubernetes distribution, users get consistent core capabilities and experience with Olares. + +### Networking + +The networking stack ensures seamless communication between containers, nodes, and services. Key components include: + +- [CoreDNS](https://coredns.io/): Provides DNS services for the cluster, ensuring efficient name resolution. +- [Calico](https://www.tigera.io/project-calico/): A container networking interface (CNI) that facilitates communication between containers and virtual machines while offering advanced network policy controls. +- [Envoy](https://www.envoyproxy.io/): A high-performance, extensible edge and service proxy. Envoy acts as middleware for communication between services, handling load balancing, service discovery, secure communication, and observability. It can operate as a standalone reverse proxy or an API gateway and is often used as a data plane component in service meshes. + +These components collectively ensure robust, scalable, and secure networking within Olares. + +### Distributed storage + +Olares provides flexibility in storage solutions tailored to both single-node and multi-node setups: + +- Local storage (default): Ideal for single-node deployments, offering the best read/write performance. +- [S3](https://aws.amazon.com/s3/): A cloud-based storage option. Ideal for cloud deployment via S3 or any S3-compatible service. +- [MinIO](https://min.io/): A distributed storage solution for self-hosted deployment. Users can either set up a MinIO cluster through Olares or mount an existing one. + +This approach ensures that applications have access to the necessary storage mechanisms, whether it's for local or distributed environments. + +### Distributed key-value storage + +Olares uses [etcd](https://etcd.io/) as its distributed key-value store. etcd is integral for storing and managing all cluster data for Kubernetes. + +### GPU management + +Olares leverages components like CUDA driver, NVIDIA device plugin, and nvShare, which work in conjunction to manage and provision GPU resources effectively: + +- CUDA: Acts as the core interface between the GPU hardware and the operating system. +- NVIDIA device plugin: Allows GPU resources to be advertised, scheduled, and allocated to containers or pods. +- [nvshare](https://github.com/grgalex/nvshare): Allows multiple containers or pods to share a single GPU, enabling both shared and exclusive GPU usage in Olares for better GPU utilization. + +:::info +Currently, Olares GPU support is restricted to deployments with one GPU per node. +::: +Starting with Olares v1.11, [CUDA](https://developer.nvidia.com/cuda-toolkit) (12.4 and above) is supported. Changes in the host environment's CUDA configuration can be synchronized with the Olares cluster using `olares-cli`. + +### Container management +Olares uses [containerd](../developer/install/installation-overview.md#container-runtime-containerd), a lightweight container runtime, for containerized deployments. + +### Olares Controller Panel + +The management of Olares is implemented through the following: + +- [olares-cli](../developer/install/cli/olares-cli.md): A command-line tool for managing Olares clusters, applications, and hardware nodes. +- [olaresd](../developer/install/installation-overview.md#container-runtime-containerd): A daemon process that monitors hardware and network changes, while also managing cluster upgrades, restarts, and other maintenance operations. + +These tools streamline installation, maintenance, and scaling for Olares. + +## Platform + +The platform layer services run in containers with middlewares such as databases, messaging system, file system, workflow orchestration, secret management, and observability. + +### Relational database + +Olares uses [PostgreSQL](https://www.postgresql.org/) 16 as its primary relational database. All applications share a single PostgreSQL instance, with each having dedicated accounts for isolation. PostgreSQL also serves as a full-text search engine and vector database. + +For multi-nodes, [Citus](https://github.com/citusdata/citus) is used, though its production readiness is still under evaluation. + +In the future, PostgreSQL is expected to migrate to the infrastructure layer for better resource management. + +### Key-value cache + +Olares integrates [KVRocks](https://github.com/apache/incubator-kvrocks), a Redis-compatible persistent key-value store built on RocksDB. KVRocks balances memory and disk storage, making it more resource-efficient than Redis clusters, though slightly slower in performance. + +### Message queue + +Olares integrates [NATS](https://nats.io/), a lightweight and high-performance message-oriented middleware, as the messaging system. NATS ensures low resource consumption while delivering reliable message queues. + +### Distributed file system + +Olares employs [JuiceFS](https://juicefs.com/), a cloud-native distributed file system, to provide POSIX-compatible interfaces for applications. When S3 or MinIO is used as the storage backend, JuiceFS ensures seamless file access across nodes. + +### Workflow management + +Olares uses [Argo Workflows](https://argoproj.github.io/) for workflow orchestration. This Kubernetes-native tool automates complex tasks, such as those required by Olares' distributed recommendation engine. Currently, this functionality is not available to third-party applications. + +### Secret management + +Two secret management solutions are integrated into Olares: + +- [Vault](https://github.com/beclab/olares/tree/main/apps/vault): Protects sensitive data like accounts, passwords, and mnemonics. It encrypts secrets, ensuring that even if the server is compromised, the data remains secure. Vault is developed by the Olares team based on [Padloc](https://padloc.app/). +- [Infisical](https://infisical.com/): A tool for managing sensitive information and preventing secret leaks in Olares development. + +### Observability + +Olares provides observability through the following: + +- [Prometheus](https://prometheus.io/): Used for system monitoring and resource usage tracking. It collects resource metrics for applications like Dashboard and Market. +- [OpenTelemetry](https://opentelemetry.io/)*: Enables tracing of request workflows within the Olares system using eBPF-based monitoring. *(In development)* + +### Other middlewares + +The Olares application store includes common middleware such as [Grafana](https://grafana.com/) for visualization, [MongoDB](https://www.mongodb.com/) for document storage, and [Chaos Mesh](https://chaos-mesh.org/) for chaos testing. + +## Application framework + +The application framework layer provides common functionality and interfaces for system and third-party applications. + +### Authentication and authorization + +Olares uses [LLDAP](https://lldap.example.com/) to manage user accounts and provide LDAP (Lightweight Directory Access Protocol) services for applications. + +Additionally, [Authelia](https://www.authelia.com/) adds authentication and authorization support, including multi-factor authentication and single sign-on (SSO). + +### Application governance + +Components for application governance include: +- [app-service](https://github.com/beclab/app-service): Handles application lifecycle management and resource allocation. +- [system-server](https://github.com/beclab/system-server): Manages permissions for inter-application API calls and handles network routing between applications and database middlewares. +- image-server: Works with app-service to manage container images required by Olares applications. +- [bfl](https://github.com/beclab/bfl): The Backend For Launcher service that aggregates backend interfaces and proxies requests for all system services, including user-isolated system and cluster information. + +### Network connectivity +Olares supports secure and flexible network connectivity through: +- Reverse proxy: Options include [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/), Olares Tunnel, and self-built FRP. +- [Tailscale](https://tailscale.com/): Enables users to securely access the system from anywhere. +- [Headscale](https://github.com/juanfont/headscale): A self-hosted implementation of the Tailscale control server. + +### File service +Components for file service include: +- File server: Provides essential file management services. +- [Seafile](https://www.seafile.com/): An open-source alternative to Dropbox for file synchronization. Olares deeply integrates Seafile, enabling users to synchronize files across multiple devices into a centralized repository. +- Drive server: Provides integration with external storage services like Google Drive, Dropbox and S3. +- Media server: Streams video files using [ffmpeg](https://github.com/FFmpeg/FFmpeg). + +### Knowledge service +Components for knowledge service include: +- Knowledge: Stores content such as web pages, videos, audio files, PDFs, and EPUBs that users collect via the browser extension or share from their mobile phones using LarePass. This repository is also utilized by the decentralized recommendation engine to store its results. +- Download: Uses [aria2](https://aria2.github.io/) and [youtube-dlp](https://github.com/yt-dlp/yt-dlp) to download files, magnet links, and online videos. +- Search: Provides full-text search for stored content in Knowledge and Files. +- [RSSHub](https://github.com/DIYgod/RSSHub): Generates RSS feeds for easier content subscription. + +### AI service + +Olares empowers AI capabilities with: +- Model serving*: Hosts AI models for applications. *(In development)* +- RAG interface*: Provides Retrieval-Augmented Generation (RAG) services for files, articles, images, and videos. *(In development)* +- Agent & workflow orchestration*: Manages agents and tool workflows. *(In development)* + +### System service + +System services include: +- Notification: Delivers system-wide notifications. +- Backup*: Supports backups for directories, applications, and clusters. *(In development)* +- Upgrade*: Supports automated system upgrades. *(In development)* + +## System applications + +System applications offer tools for managing files, knowledge, passwords, and the system itself. These applications are pre-installed. + +Users can install additional applications via the Market app. + +### Files + +A file management app that manages and synchronizes files across devices and sources, enabling seamless sharing and access. + +### Wise + +A local-first and AI-native modern reader that helps to collect, read, and manage information from various platforms. Users can run self-hosted recommendation algorithms to filter and sort online content. + +### Vault + +A secure password manager for storing and mangaging sensitive information across devices. + +### Market + +A decentralized and permissionless app store for installing, uninstalling, and updating applications and recommendation algorithms. + +### Desktop + +A hub for managing and interacting with installed applications. File and application searching are also supported. + +### Profile + +An app to customize the user's profile page. + +### Settings + +A system configuration application. + +### Dashboard + +An app for monitoring system resource usage. + +### Control Hub + +The console for Olares, providing precise and autonomous control over the system and its environment. + +### DevBox + +A development tool for building and deploying Olares applications. + +## Learn more +- To get started with Olares, see the [Getting Started guide](get-started/index.md). +- To learn more about the internals of Olares, see the topics in [Concept](concepts/index.md). +- For in-depth details about how each component of Olares is orchestrated, see [Olares installation overview](../developer/install/index.md). \ No newline at end of file diff --git a/docs/manual/what-is-olares.md b/docs/manual/what-is-olares.md new file mode 100644 index 000000000..1bc8eeede --- /dev/null +++ b/docs/manual/what-is-olares.md @@ -0,0 +1,15 @@ +# What is Olares + +Olares is the sovereign cloud that puts you in control. It's an open-source, self-hosted alternative to public clouds like AWS, built to reclaim your data ownership and privacy. By combining the power of Kubernetes with a streamlined interface, Olares enables you to take full control of your data and computing resources. Whether you're managing a homelab, hosting applications, or safeguarding your privacy, Olares delivers the flexibility and capabilities of public clouds, without compromising privacy or security. + +## What can you do with Olares +Typical use cases of Olares include: + +- 🖥️ **Homelab server**: Turn your personal devices into a versatile homelab for experimenting with containerized applications, running local AI models, managing self-hosted services, or testing cloud technologies—all within your own private infrastructure. +- 🤖 **Local AI**: Host and run cutting-edge open-source AI models—including large language models, image generation, and speech recognition—directly on your devices. Build custom AI assistants that integrate with your data and applications while keeping everything private and secure. +- 💻 **Personal data repository**: Securely store, sync, and manage your photos, documents, and important files in a unified, private storage system accessible from anywhere. +- 🛠️ **Self-hosted workspace**: Create a free, collaborative workspace for your team or family with open-source alternatives to commercial productivity tools. +- 🎥 **Private media server**: Turn your personal media collection into your own streaming service, hosted entirely on your devices. +- 🏡 **Smart home**: Use Olares as the central control point for managing IoT devices and home automation. +- 🤝 **Decentralized social media**: Host decentralized social media platforms like Mastodon, Ghost, or WordPress to build your personal brand without the risks of bans or platform fees. + diff --git a/docs/manual/why-olares.md b/docs/manual/why-olares.md new file mode 100644 index 000000000..b3e588195 --- /dev/null +++ b/docs/manual/why-olares.md @@ -0,0 +1,33 @@ +--- +description: Explore key use cases for Olares including edge AI, personal data management, self-hosted workspace, private media server, smart home control, and decentralized social media deployment. +--- +# Why Olares +Here are some typical use scenarios for Olares. + +🤖 **Edge AI**: + +Run cutting-edge open AI models locally, including large language models, computer vision, and speech recognition. Create private AI services tailored to your data for enhanced functionality and privacy. + +📊 **Personal data repository**: + +Securely store, sync, and manage your important files, photos, and documents across devices and locations. + +🚀 **Self-hosted workspace**: + +Build a free collaborative workspace for your team using secure, open-source SaaS alternatives. + +🎥 **Private media server**: + +Host your own streaming services with your personal media collections. + +🏡 Smart home + +Create a central control point for your IoT devices and home automation. + +🤝 Decentralized social media + +Easily install decentralized social media apps such as Mastodon, Ghost, and WordPress on Olares, allowing you to build a personal brand without the risk of being banned or paying platform commissions. + +📚 Learning platform + +Explore self-hosting, container orchestration, and cloud technologies hands-on. \ No newline at end of file diff --git a/docs/package-lock.json b/docs/package-lock.json new file mode 100644 index 000000000..57509a832 --- /dev/null +++ b/docs/package-lock.json @@ -0,0 +1,4216 @@ +{ + "name": "docs", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "dependencies": { + "@vercel/analytics": "^1.2.2", + "@vercel/speed-insights": "^1.0.10", + "lodash": "^4.17.21", + "medium-zoom": "^1.1.0", + "sitemap": "^7.1.1" + }, + "devDependencies": { + "mermaid": "10.9.3", + "terser": "^5.14.2", + "vitepress": "1.6.3", + "vitepress-plugin-mermaid": "2.0.17" + } + }, + "node_modules/@algolia/autocomplete-core": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@algolia/autocomplete-core/-/autocomplete-core-1.17.7.tgz", + "integrity": "sha512-BjiPOW6ks90UKl7TwMv7oNQMnzU+t/wk9mgIDi6b1tXpUek7MW0lbNOUHpvam9pe3lVCf4xPFT+lK7s+e+fs7Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/autocomplete-plugin-algolia-insights": "1.17.7", + "@algolia/autocomplete-shared": "1.17.7" + } + }, + "node_modules/@algolia/autocomplete-plugin-algolia-insights": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@algolia/autocomplete-plugin-algolia-insights/-/autocomplete-plugin-algolia-insights-1.17.7.tgz", + "integrity": "sha512-Jca5Ude6yUOuyzjnz57og7Et3aXjbwCSDf/8onLHSQgw1qW3ALl9mrMWaXb5FmPVkV3EtkD2F/+NkT6VHyPu9A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/autocomplete-shared": "1.17.7" + }, + "peerDependencies": { + "search-insights": ">= 1 < 3" + } + }, + "node_modules/@algolia/autocomplete-preset-algolia": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@algolia/autocomplete-preset-algolia/-/autocomplete-preset-algolia-1.17.7.tgz", + "integrity": "sha512-ggOQ950+nwbWROq2MOCIL71RE0DdQZsceqrg32UqnhDz8FlO9rL8ONHNsI2R1MH0tkgVIDKI/D0sMiUchsFdWA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/autocomplete-shared": "1.17.7" + }, + "peerDependencies": { + "@algolia/client-search": ">= 4.9.1 < 6", + "algoliasearch": ">= 4.9.1 < 6" + } + }, + "node_modules/@algolia/autocomplete-shared": { + "version": "1.17.7", + "resolved": "https://registry.npmjs.org/@algolia/autocomplete-shared/-/autocomplete-shared-1.17.7.tgz", + "integrity": "sha512-o/1Vurr42U/qskRSuhBH+VKxMvkkUVTLU6WZQr+L5lGZZLYWyhdzWjW0iGXY7EkwRTjBqvN2EsR81yCTGV/kmg==", + "dev": true, + "license": "MIT", + "peerDependencies": { + "@algolia/client-search": ">= 4.9.1 < 6", + "algoliasearch": ">= 4.9.1 < 6" + } + }, + "node_modules/@algolia/client-abtesting": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/client-abtesting/-/client-abtesting-5.32.0.tgz", + "integrity": "sha512-HG/6Eib6DnJYm/B2ijWFXr4txca/YOuA4K7AsEU0JBrOZSB+RU7oeDyNBPi3c0v0UDDqlkBqM3vBU/auwZlglA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/client-analytics": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/client-analytics/-/client-analytics-5.32.0.tgz", + "integrity": "sha512-8Y9MLU72WFQOW3HArYv16+Wvm6eGmsqbxxM1qxtm0hvSASJbxCm+zQAZe5stqysTlcWo4BJ82KEH1PfgHbJAmQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/client-common": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/client-common/-/client-common-5.32.0.tgz", + "integrity": "sha512-w8L+rgyXMCPBKmEdOT+RfgMrF0mT6HK60vPYWLz8DBs/P7yFdGo7urn99XCJvVLMSKXrIbZ2FMZ/i50nZTXnuQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/client-insights": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/client-insights/-/client-insights-5.32.0.tgz", + "integrity": "sha512-AdWfynhUeX7jz/LTiFU3wwzJembTbdLkQIOLs4n7PyBuxZ3jz4azV1CWbIP8AjUOFmul6uXbmYza+KqyS5CzOA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/client-personalization": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/client-personalization/-/client-personalization-5.32.0.tgz", + "integrity": "sha512-bTupJY4xzGZYI4cEQcPlSjjIEzMvv80h7zXGrXY1Y0KC/n/SLiMv84v7Uy+B6AG1Kiy9FQm2ADChBLo1uEhGtQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/client-query-suggestions": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/client-query-suggestions/-/client-query-suggestions-5.32.0.tgz", + "integrity": "sha512-if+YTJw1G3nDKL2omSBjQltCHUQzbaHADkcPQrGFnIGhVyHU3Dzq4g46uEv8mrL5sxL8FjiS9LvekeUlL2NRqw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/client-search": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/client-search/-/client-search-5.32.0.tgz", + "integrity": "sha512-kmK5nVkKb4DSUgwbveMKe4X3xHdMsPsOVJeEzBvFJ+oS7CkBPmpfHAEq+CcmiPJs20YMv6yVtUT9yPWL5WgAhg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/ingestion": { + "version": "1.32.0", + "resolved": "https://registry.npmjs.org/@algolia/ingestion/-/ingestion-1.32.0.tgz", + "integrity": "sha512-PZTqjJbx+fmPuT2ud1n4vYDSF1yrT//vOGI9HNYKNA0PM0xGUBWigf5gRivHsXa3oBnUlTyHV9j7Kqx5BHbVHQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/monitoring": { + "version": "1.32.0", + "resolved": "https://registry.npmjs.org/@algolia/monitoring/-/monitoring-1.32.0.tgz", + "integrity": "sha512-kYYoOGjvNQAmHDS1v5sBj+0uEL9RzYqH/TAdq8wmcV+/22weKt/fjh+6LfiqkS1SCZFYYrwGnirrUhUM36lBIQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/recommend": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/recommend/-/recommend-5.32.0.tgz", + "integrity": "sha512-jyIBLdskjPAL7T1g57UMfUNx+PzvYbxKslwRUKBrBA6sNEsYCFdxJAtZSLUMmw6MC98RDt4ksmEl5zVMT5bsuw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/requester-browser-xhr": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/requester-browser-xhr/-/requester-browser-xhr-5.32.0.tgz", + "integrity": "sha512-eDp14z92Gt6JlFgiexImcWWH+Lk07s/FtxcoDaGrE4UVBgpwqOO6AfQM6dXh1pvHxlDFbMJihHc/vj3gBhPjqQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/requester-fetch": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/requester-fetch/-/requester-fetch-5.32.0.tgz", + "integrity": "sha512-rnWVglh/K75hnaLbwSc2t7gCkbq1ldbPgeIKDUiEJxZ4mlguFgcltWjzpDQ/t1LQgxk9HdIFcQfM17Hid3aQ6Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@algolia/requester-node-http": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/@algolia/requester-node-http/-/requester-node-http-5.32.0.tgz", + "integrity": "sha512-LbzQ04+VLkzXY4LuOzgyjqEv/46Gwrk55PldaglMJ4i4eDXSRXGKkwJpXFwsoU+c1HMQlHIyjJBhrfsfdyRmyQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-common": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/@babel/helper-string-parser": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz", + "integrity": "sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==", + "devOptional": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/helper-validator-identifier": { + "version": "7.27.1", + "resolved": "https://registry.npmjs.org/@babel/helper-validator-identifier/-/helper-validator-identifier-7.27.1.tgz", + "integrity": "sha512-D2hP9eA+Sqx1kBZgzxZh0y1trbuU+JoDkiEwqhQ36nodYqJwyEIhPSdMNd7lOm/4io72luTPWH20Yda0xOuUow==", + "devOptional": true, + "license": "MIT", + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@babel/parser": { + "version": "7.28.0", + "resolved": "https://registry.npmjs.org/@babel/parser/-/parser-7.28.0.tgz", + "integrity": "sha512-jVZGvOxOuNSsuQuLRTh13nU0AogFlw32w/MT+LV6D3sP5WdbW61E77RnkbaO2dUvmPAYrBDJXGn5gGS6tH4j8g==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@babel/types": "^7.28.0" + }, + "bin": { + "parser": "bin/babel-parser.js" + }, + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@babel/types": { + "version": "7.28.0", + "resolved": "https://registry.npmjs.org/@babel/types/-/types-7.28.0.tgz", + "integrity": "sha512-jYnje+JyZG5YThjHiF28oT4SIZLnYOcSBb6+SDaFIyzDVSkXQmQQYclJ2R+YxcdmK0AX6x1E5OQNtuh3jHDrUg==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@babel/helper-string-parser": "^7.27.1", + "@babel/helper-validator-identifier": "^7.27.1" + }, + "engines": { + "node": ">=6.9.0" + } + }, + "node_modules/@braintree/sanitize-url": { + "version": "6.0.4", + "resolved": "https://registry.npmjs.org/@braintree/sanitize-url/-/sanitize-url-6.0.4.tgz", + "integrity": "sha512-s3jaWicZd0pkP0jf5ysyHUI/RE7MHos6qlToFcGWXVp+ykHOy77OUMrfbgJ9it2C5bow7OIQwYYaHjk9XlBQ2A==", + "dev": true, + "license": "MIT" + }, + "node_modules/@docsearch/css": { + "version": "3.8.2", + "resolved": "https://registry.npmjs.org/@docsearch/css/-/css-3.8.2.tgz", + "integrity": "sha512-y05ayQFyUmCXze79+56v/4HpycYF3uFqB78pLPrSV5ZKAlDuIAAJNhaRi8tTdRNXh05yxX/TyNnzD6LwSM89vQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@docsearch/js": { + "version": "3.8.2", + "resolved": "https://registry.npmjs.org/@docsearch/js/-/js-3.8.2.tgz", + "integrity": "sha512-Q5wY66qHn0SwA7Taa0aDbHiJvaFJLOJyHmooQ7y8hlwwQLQ/5WwCcoX0g7ii04Qi2DJlHsd0XXzJ8Ypw9+9YmQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@docsearch/react": "3.8.2", + "preact": "^10.0.0" + } + }, + "node_modules/@docsearch/react": { + "version": "3.8.2", + "resolved": "https://registry.npmjs.org/@docsearch/react/-/react-3.8.2.tgz", + "integrity": "sha512-xCRrJQlTt8N9GU0DG4ptwHRkfnSnD/YpdeaXe02iKfqs97TkZJv60yE+1eq/tjPcVnTW8dP5qLP7itifFVV5eg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/autocomplete-core": "1.17.7", + "@algolia/autocomplete-preset-algolia": "1.17.7", + "@docsearch/css": "3.8.2", + "algoliasearch": "^5.14.2" + }, + "peerDependencies": { + "@types/react": ">= 16.8.0 < 19.0.0", + "react": ">= 16.8.0 < 19.0.0", + "react-dom": ">= 16.8.0 < 19.0.0", + "search-insights": ">= 1 < 3" + }, + "peerDependenciesMeta": { + "@types/react": { + "optional": true + }, + "react": { + "optional": true + }, + "react-dom": { + "optional": true + }, + "search-insights": { + "optional": true + } + } + }, + "node_modules/@esbuild/aix-ppc64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.21.5.tgz", + "integrity": "sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-arm": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.21.5.tgz", + "integrity": "sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.21.5.tgz", + "integrity": "sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/android-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.21.5.tgz", + "integrity": "sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/darwin-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.21.5.tgz", + "integrity": "sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/darwin-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.21.5.tgz", + "integrity": "sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/freebsd-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.21.5.tgz", + "integrity": "sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/freebsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.21.5.tgz", + "integrity": "sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-arm": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.21.5.tgz", + "integrity": "sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.21.5.tgz", + "integrity": "sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-ia32": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.21.5.tgz", + "integrity": "sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-loong64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.21.5.tgz", + "integrity": "sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-mips64el": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.21.5.tgz", + "integrity": "sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-ppc64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.21.5.tgz", + "integrity": "sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-riscv64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.21.5.tgz", + "integrity": "sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-s390x": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.21.5.tgz", + "integrity": "sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/linux-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz", + "integrity": "sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/netbsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.21.5.tgz", + "integrity": "sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/openbsd-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.21.5.tgz", + "integrity": "sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/sunos-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.21.5.tgz", + "integrity": "sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-arm64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.21.5.tgz", + "integrity": "sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-ia32": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.21.5.tgz", + "integrity": "sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@esbuild/win32-x64": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.21.5.tgz", + "integrity": "sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=12" + } + }, + "node_modules/@iconify-json/simple-icons": { + "version": "1.2.42", + "resolved": "https://registry.npmjs.org/@iconify-json/simple-icons/-/simple-icons-1.2.42.tgz", + "integrity": "sha512-G/EED0hUV1wMNUsWaFdQYLibm6SO7rP2GZP1+CvhszB5WAFYYibD3zoWp3X96xSIWpYQFvccvE17ewpd0Q1hWQ==", + "dev": true, + "license": "CC0-1.0", + "dependencies": { + "@iconify/types": "*" + } + }, + "node_modules/@iconify/types": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@iconify/types/-/types-2.0.0.tgz", + "integrity": "sha512-+wluvCrRhXrhyOmRDJ3q8mux9JkKy5SJ/v8ol2tu4FVjyYvtEzkc/3pK15ET6RKg4b4w4BmTk1+gsCUhf21Ykg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@jridgewell/gen-mapping": { + "version": "0.3.12", + "resolved": "https://registry.npmjs.org/@jridgewell/gen-mapping/-/gen-mapping-0.3.12.tgz", + "integrity": "sha512-OuLGC46TjB5BbN1dH8JULVVZY4WTdkF7tV9Ys6wLL1rubZnCMstOhNHueU5bLCrnRuDhKPDM4g6sw4Bel5Gzqg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.0", + "@jridgewell/trace-mapping": "^0.3.24" + } + }, + "node_modules/@jridgewell/resolve-uri": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz", + "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.0.0" + } + }, + "node_modules/@jridgewell/source-map": { + "version": "0.3.10", + "resolved": "https://registry.npmjs.org/@jridgewell/source-map/-/source-map-0.3.10.tgz", + "integrity": "sha512-0pPkgz9dY+bijgistcTTJ5mR+ocqRXLuhXHYdzoMmmoJ2C9S46RCm2GMUbatPEUK9Yjy26IrAy8D/M00lLkv+Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/gen-mapping": "^0.3.5", + "@jridgewell/trace-mapping": "^0.3.25" + } + }, + "node_modules/@jridgewell/sourcemap-codec": { + "version": "1.5.4", + "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.4.tgz", + "integrity": "sha512-VT2+G1VQs/9oz078bLrYbecdZKs912zQlkelYpuf+SXF+QvZDYJlbx/LSx+meSAwdDFnF8FVXW92AVjjkVmgFw==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/@jridgewell/trace-mapping": { + "version": "0.3.29", + "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.29.tgz", + "integrity": "sha512-uw6guiW/gcAGPDhLmd77/6lW8QLeiV5RUTsAX46Db6oLhGaVj4lhnPwb184s1bkc8kdVg/+h988dro8GRDpmYQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@jridgewell/resolve-uri": "^3.1.0", + "@jridgewell/sourcemap-codec": "^1.4.14" + } + }, + "node_modules/@mermaid-js/mermaid-mindmap": { + "version": "9.3.0", + "resolved": "https://registry.npmjs.org/@mermaid-js/mermaid-mindmap/-/mermaid-mindmap-9.3.0.tgz", + "integrity": "sha512-IhtYSVBBRYviH1Ehu8gk69pMDF8DSRqXBRDMWrEfHoaMruHeaP2DXA3PBnuwsMaCdPQhlUUcy/7DBLAEIXvCAw==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "@braintree/sanitize-url": "^6.0.0", + "cytoscape": "^3.23.0", + "cytoscape-cose-bilkent": "^4.1.0", + "cytoscape-fcose": "^2.1.0", + "d3": "^7.0.0", + "khroma": "^2.0.0", + "non-layered-tidy-tree-layout": "^2.0.2" + } + }, + "node_modules/@rollup/rollup-android-arm-eabi": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.44.2.tgz", + "integrity": "sha512-g0dF8P1e2QYPOj1gu7s/3LVP6kze9A7m6x0BZ9iTdXK8N5c2V7cpBKHV3/9A4Zd8xxavdhK0t4PnqjkqVmUc9Q==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-android-arm64": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm64/-/rollup-android-arm64-4.44.2.tgz", + "integrity": "sha512-Yt5MKrOosSbSaAK5Y4J+vSiID57sOvpBNBR6K7xAaQvk3MkcNVV0f9fE20T+41WYN8hDn6SGFlFrKudtx4EoxA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "android" + ] + }, + "node_modules/@rollup/rollup-darwin-arm64": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-arm64/-/rollup-darwin-arm64-4.44.2.tgz", + "integrity": "sha512-EsnFot9ZieM35YNA26nhbLTJBHD0jTwWpPwmRVDzjylQT6gkar+zenfb8mHxWpRrbn+WytRRjE0WKsfaxBkVUA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-darwin-x64": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-darwin-x64/-/rollup-darwin-x64-4.44.2.tgz", + "integrity": "sha512-dv/t1t1RkCvJdWWxQ2lWOO+b7cMsVw5YFaS04oHpZRWehI1h0fV1gF4wgGCTyQHHjJDfbNpwOi6PXEafRBBezw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ] + }, + "node_modules/@rollup/rollup-freebsd-arm64": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-arm64/-/rollup-freebsd-arm64-4.44.2.tgz", + "integrity": "sha512-W4tt4BLorKND4qeHElxDoim0+BsprFTwb+vriVQnFFtT/P6v/xO5I99xvYnVzKWrK6j7Hb0yp3x7V5LUbaeOMg==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-freebsd-x64": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-freebsd-x64/-/rollup-freebsd-x64-4.44.2.tgz", + "integrity": "sha512-tdT1PHopokkuBVyHjvYehnIe20fxibxFCEhQP/96MDSOcyjM/shlTkZZLOufV3qO6/FQOSiJTBebhVc12JyPTA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "freebsd" + ] + }, + "node_modules/@rollup/rollup-linux-arm-gnueabihf": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-gnueabihf/-/rollup-linux-arm-gnueabihf-4.44.2.tgz", + "integrity": "sha512-+xmiDGGaSfIIOXMzkhJ++Oa0Gwvl9oXUeIiwarsdRXSe27HUIvjbSIpPxvnNsRebsNdUo7uAiQVgBD1hVriwSQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm-musleabihf": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm-musleabihf/-/rollup-linux-arm-musleabihf-4.44.2.tgz", + "integrity": "sha512-bDHvhzOfORk3wt8yxIra8N4k/N0MnKInCW5OGZaeDYa/hMrdPaJzo7CSkjKZqX4JFUWjUGm88lI6QJLCM7lDrA==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-gnu": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-gnu/-/rollup-linux-arm64-gnu-4.44.2.tgz", + "integrity": "sha512-NMsDEsDiYghTbeZWEGnNi4F0hSbGnsuOG+VnNvxkKg0IGDvFh7UVpM/14mnMwxRxUf9AdAVJgHPvKXf6FpMB7A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-arm64-musl": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-arm64-musl/-/rollup-linux-arm64-musl-4.44.2.tgz", + "integrity": "sha512-lb5bxXnxXglVq+7imxykIp5xMq+idehfl+wOgiiix0191av84OqbjUED+PRC5OA8eFJYj5xAGcpAZ0pF2MnW+A==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-loongarch64-gnu": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-loongarch64-gnu/-/rollup-linux-loongarch64-gnu-4.44.2.tgz", + "integrity": "sha512-Yl5Rdpf9pIc4GW1PmkUGHdMtbx0fBLE1//SxDmuf3X0dUC57+zMepow2LK0V21661cjXdTn8hO2tXDdAWAqE5g==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-powerpc64le-gnu": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-powerpc64le-gnu/-/rollup-linux-powerpc64le-gnu-4.44.2.tgz", + "integrity": "sha512-03vUDH+w55s680YYryyr78jsO1RWU9ocRMaeV2vMniJJW/6HhoTBwyyiiTPVHNWLnhsnwcQ0oH3S9JSBEKuyqw==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-gnu": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-gnu/-/rollup-linux-riscv64-gnu-4.44.2.tgz", + "integrity": "sha512-iYtAqBg5eEMG4dEfVlkqo05xMOk6y/JXIToRca2bAWuqjrJYJlx/I7+Z+4hSrsWU8GdJDFPL4ktV3dy4yBSrzg==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-riscv64-musl": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-riscv64-musl/-/rollup-linux-riscv64-musl-4.44.2.tgz", + "integrity": "sha512-e6vEbgaaqz2yEHqtkPXa28fFuBGmUJ0N2dOJK8YUfijejInt9gfCSA7YDdJ4nYlv67JfP3+PSWFX4IVw/xRIPg==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-s390x-gnu": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-s390x-gnu/-/rollup-linux-s390x-gnu-4.44.2.tgz", + "integrity": "sha512-evFOtkmVdY3udE+0QKrV5wBx7bKI0iHz5yEVx5WqDJkxp9YQefy4Mpx3RajIVcM6o7jxTvVd/qpC1IXUhGc1Mw==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-gnu": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-gnu/-/rollup-linux-x64-gnu-4.44.2.tgz", + "integrity": "sha512-/bXb0bEsWMyEkIsUL2Yt5nFB5naLAwyOWMEviQfQY1x3l5WsLKgvZf66TM7UTfED6erckUVUJQ/jJ1FSpm3pRQ==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-linux-x64-musl": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-linux-x64-musl/-/rollup-linux-x64-musl-4.44.2.tgz", + "integrity": "sha512-3D3OB1vSSBXmkGEZR27uiMRNiwN08/RVAcBKwhUYPaiZ8bcvdeEwWPvbnXvvXHY+A/7xluzcN+kaiOFNiOZwWg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "linux" + ] + }, + "node_modules/@rollup/rollup-win32-arm64-msvc": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-arm64-msvc/-/rollup-win32-arm64-msvc-4.44.2.tgz", + "integrity": "sha512-VfU0fsMK+rwdK8mwODqYeM2hDrF2WiHaSmCBrS7gColkQft95/8tphyzv2EupVxn3iE0FI78wzffoULH1G+dkw==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-ia32-msvc": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-ia32-msvc/-/rollup-win32-ia32-msvc-4.44.2.tgz", + "integrity": "sha512-+qMUrkbUurpE6DVRjiJCNGZBGo9xM4Y0FXU5cjgudWqIBWbcLkjE3XprJUsOFgC6xjBClwVa9k6O3A7K3vxb5Q==", + "cpu": [ + "ia32" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@rollup/rollup-win32-x64-msvc": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/@rollup/rollup-win32-x64-msvc/-/rollup-win32-x64-msvc-4.44.2.tgz", + "integrity": "sha512-3+QZROYfJ25PDcxFF66UEk8jGWigHJeecZILvkPkyQN7oc5BvFo4YEXFkOs154j3FTMp9mn9Ky8RCOwastduEA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "MIT", + "optional": true, + "os": [ + "win32" + ] + }, + "node_modules/@shikijs/core": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/core/-/core-2.5.0.tgz", + "integrity": "sha512-uu/8RExTKtavlpH7XqnVYBrfBkUc20ngXiX9NSrBhOVZYv/7XQRKUyhtkeflY5QsxC0GbJThCerruZfsUaSldg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/engine-javascript": "2.5.0", + "@shikijs/engine-oniguruma": "2.5.0", + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4", + "hast-util-to-html": "^9.0.4" + } + }, + "node_modules/@shikijs/engine-javascript": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-javascript/-/engine-javascript-2.5.0.tgz", + "integrity": "sha512-VjnOpnQf8WuCEZtNUdjjwGUbtAVKuZkVQ/5cHy/tojVVRIRtlWMYVjyWhxOmIq05AlSOv72z7hRNRGVBgQOl0w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2", + "oniguruma-to-es": "^3.1.0" + } + }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-2.5.0.tgz", + "integrity": "sha512-pGd1wRATzbo/uatrCIILlAdFVKdxImWJGQ5rFiB5VZi2ve5xj3Ax9jny8QvkaV93btQEwR/rSz5ERFpC5mKNIw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, + "node_modules/@shikijs/langs": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-2.5.0.tgz", + "integrity": "sha512-Qfrrt5OsNH5R+5tJ/3uYBBZv3SuGmnRPejV9IlIbFH3HTGLDlkqgHymAlzklVmKBjAaVmkPkyikAV/sQ1wSL+w==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0" + } + }, + "node_modules/@shikijs/themes": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-2.5.0.tgz", + "integrity": "sha512-wGrk+R8tJnO0VMzmUExHR+QdSaPUl/NKs+a4cQQRWyoc3YFbUzuLEi/KWK1hj+8BfHRKm2jNhhJck1dfstJpiw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "2.5.0" + } + }, + "node_modules/@shikijs/transformers": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/transformers/-/transformers-2.5.0.tgz", + "integrity": "sha512-SI494W5X60CaUwgi8u4q4m4s3YAFSxln3tzNjOSYqq54wlVgz0/NbbXEb3mdLbqMBztcmS7bVTaEd2w0qMmfeg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "2.5.0", + "@shikijs/types": "2.5.0" + } + }, + "node_modules/@shikijs/types": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-2.5.0.tgz", + "integrity": "sha512-ygl5yhxki9ZLNuNpPitBWvcy9fsSKKaRuO4BAlMyagszQidxcpLAr0qiW/q43DtSIDxO6hEbtYLiFZNXO/hdGw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz", + "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/d3-scale": { + "version": "4.0.9", + "resolved": "https://registry.npmjs.org/@types/d3-scale/-/d3-scale-4.0.9.tgz", + "integrity": "sha512-dLmtwB8zkAeO/juAMfnV+sItKjlsw2lKdZVVy6LRr0cBmegxSABiLEpGVmSJJ8O08i4+sGR6qQtb6WtuwJdvVw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/d3-time": "*" + } + }, + "node_modules/@types/d3-scale-chromatic": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/@types/d3-scale-chromatic/-/d3-scale-chromatic-3.1.0.tgz", + "integrity": "sha512-iWMJgwkK7yTRmWqRB5plb1kadXyQ5Sj8V/zYlFGMUBbIPKQScw+Dku9cAAMgJG+z5GYDoMjWGLVOvjghDEFnKQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/d3-time": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/d3-time/-/d3-time-3.0.4.tgz", + "integrity": "sha512-yuzZug1nkAAaBlBBikKZTgzCeA+k1uy4ZFwWANOfKw5z5LRhV0gNA7gNkKm7HoK+HRN0wX3EkxGk0fpbWhmB7g==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/debug": { + "version": "4.1.12", + "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz", + "integrity": "sha512-vIChWdVG3LG1SMxEvI/AK+FWJthlrqlTu7fbrlywTkkaONwk/UAGaULXRlf8vkzFBLVm0zkMdCquhL5aOjhXPQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/ms": "*" + } + }, + "node_modules/@types/estree": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/@types/estree/-/estree-1.0.8.tgz", + "integrity": "sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/@types/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/@types/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/markdown-it": { + "version": "14.1.2", + "resolved": "https://registry.npmjs.org/@types/markdown-it/-/markdown-it-14.1.2.tgz", + "integrity": "sha512-promo4eFwuiW+TfGxhi+0x3czqTYJkG8qB17ZUJiVF10Xm7NLVRSLUsfRTU/6h1e24VvRnXCx+hG7li58lkzog==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/linkify-it": "^5", + "@types/mdurl": "^2" + } + }, + "node_modules/@types/mdast": { + "version": "3.0.15", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-3.0.15.tgz", + "integrity": "sha512-LnwD+mUEfxWMa1QpDraczIn6k0Ee3SMicuYSSzS6ZYl2gKS09EClnJYGd8Du6rfc5r/GZEk5o1mRb8TaTj03sQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^2" + } + }, + "node_modules/@types/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/@types/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/ms": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/@types/ms/-/ms-2.1.0.tgz", + "integrity": "sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/node": { + "version": "17.0.45", + "resolved": "https://registry.npmjs.org/@types/node/-/node-17.0.45.tgz", + "integrity": "sha512-w+tIMs3rq2afQdsPJlODhoUEKzFP1ayaoyl1CcnwtIlsVe7K7bA1NGm4s3PraqTLlXnbIN84zuBlxBWo1u9BLw==", + "license": "MIT" + }, + "node_modules/@types/sax": { + "version": "1.2.7", + "resolved": "https://registry.npmjs.org/@types/sax/-/sax-1.2.7.tgz", + "integrity": "sha512-rO73L89PJxeYM3s3pPPjiPgVVcymqU490g0YO5n5By0k2Erzj6tay/4lr1CHAAU4JyOWd1rpQ8bCf6cZfHU96A==", + "license": "MIT", + "dependencies": { + "@types/node": "*" + } + }, + "node_modules/@types/unist": { + "version": "2.0.11", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-2.0.11.tgz", + "integrity": "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@types/web-bluetooth": { + "version": "0.0.21", + "resolved": "https://registry.npmjs.org/@types/web-bluetooth/-/web-bluetooth-0.0.21.tgz", + "integrity": "sha512-oIQLCGWtcFZy2JW77j9k8nHzAOpqMHLQejDA48XXMWH6tjCQHz5RCFz1bzsmROyL6PUm+LLnUiI4BCn221inxA==", + "dev": true, + "license": "MIT" + }, + "node_modules/@ungap/structured-clone": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.0.tgz", + "integrity": "sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==", + "dev": true, + "license": "ISC" + }, + "node_modules/@vercel/analytics": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/@vercel/analytics/-/analytics-1.5.0.tgz", + "integrity": "sha512-MYsBzfPki4gthY5HnYN7jgInhAZ7Ac1cYDoRWFomwGHWEX7odTEzbtg9kf/QSo7XEsEAqlQugA6gJ2WS2DEa3g==", + "license": "MPL-2.0", + "peerDependencies": { + "@remix-run/react": "^2", + "@sveltejs/kit": "^1 || ^2", + "next": ">= 13", + "react": "^18 || ^19 || ^19.0.0-rc", + "svelte": ">= 4", + "vue": "^3", + "vue-router": "^4" + }, + "peerDependenciesMeta": { + "@remix-run/react": { + "optional": true + }, + "@sveltejs/kit": { + "optional": true + }, + "next": { + "optional": true + }, + "react": { + "optional": true + }, + "svelte": { + "optional": true + }, + "vue": { + "optional": true + }, + "vue-router": { + "optional": true + } + } + }, + "node_modules/@vercel/speed-insights": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/@vercel/speed-insights/-/speed-insights-1.2.0.tgz", + "integrity": "sha512-y9GVzrUJ2xmgtQlzFP2KhVRoCglwfRQgjyfY607aU0hh0Un6d0OUyrJkjuAlsV18qR4zfoFPs/BiIj9YDS6Wzw==", + "hasInstallScript": true, + "license": "Apache-2.0", + "peerDependencies": { + "@sveltejs/kit": "^1 || ^2", + "next": ">= 13", + "react": "^18 || ^19 || ^19.0.0-rc", + "svelte": ">= 4", + "vue": "^3", + "vue-router": "^4" + }, + "peerDependenciesMeta": { + "@sveltejs/kit": { + "optional": true + }, + "next": { + "optional": true + }, + "react": { + "optional": true + }, + "svelte": { + "optional": true + }, + "vue": { + "optional": true + }, + "vue-router": { + "optional": true + } + } + }, + "node_modules/@vue/compiler-core": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/compiler-core/-/compiler-core-3.5.17.tgz", + "integrity": "sha512-Xe+AittLbAyV0pabcN7cP7/BenRBNcteM4aSDCtRvGw0d9OL+HG1u/XHLY/kt1q4fyMeZYXyIYrsHuPSiDPosA==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.27.5", + "@vue/shared": "3.5.17", + "entities": "^4.5.0", + "estree-walker": "^2.0.2", + "source-map-js": "^1.2.1" + } + }, + "node_modules/@vue/compiler-dom": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/compiler-dom/-/compiler-dom-3.5.17.tgz", + "integrity": "sha512-+2UgfLKoaNLhgfhV5Ihnk6wB4ljyW1/7wUIog2puUqajiC29Lp5R/IKDdkebh9jTbTogTbsgB+OY9cEWzG95JQ==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-core": "3.5.17", + "@vue/shared": "3.5.17" + } + }, + "node_modules/@vue/compiler-sfc": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/compiler-sfc/-/compiler-sfc-3.5.17.tgz", + "integrity": "sha512-rQQxbRJMgTqwRugtjw0cnyQv9cP4/4BxWfTdRBkqsTfLOHWykLzbOc3C4GGzAmdMDxhzU/1Ija5bTjMVrddqww==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@babel/parser": "^7.27.5", + "@vue/compiler-core": "3.5.17", + "@vue/compiler-dom": "3.5.17", + "@vue/compiler-ssr": "3.5.17", + "@vue/shared": "3.5.17", + "estree-walker": "^2.0.2", + "magic-string": "^0.30.17", + "postcss": "^8.5.6", + "source-map-js": "^1.2.1" + } + }, + "node_modules/@vue/compiler-ssr": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/compiler-ssr/-/compiler-ssr-3.5.17.tgz", + "integrity": "sha512-hkDbA0Q20ZzGgpj5uZjb9rBzQtIHLS78mMilwrlpWk2Ep37DYntUz0PonQ6kr113vfOEdM+zTBuJDaceNIW0tQ==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-dom": "3.5.17", + "@vue/shared": "3.5.17" + } + }, + "node_modules/@vue/devtools-api": { + "version": "7.7.7", + "resolved": "https://registry.npmjs.org/@vue/devtools-api/-/devtools-api-7.7.7.tgz", + "integrity": "sha512-lwOnNBH2e7x1fIIbVT7yF5D+YWhqELm55/4ZKf45R9T8r9dE2AIOy8HKjfqzGsoTHFbWbr337O4E0A0QADnjBg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/devtools-kit": "^7.7.7" + } + }, + "node_modules/@vue/devtools-kit": { + "version": "7.7.7", + "resolved": "https://registry.npmjs.org/@vue/devtools-kit/-/devtools-kit-7.7.7.tgz", + "integrity": "sha512-wgoZtxcTta65cnZ1Q6MbAfePVFxfM+gq0saaeytoph7nEa7yMXoi6sCPy4ufO111B9msnw0VOWjPEFCXuAKRHA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vue/devtools-shared": "^7.7.7", + "birpc": "^2.3.0", + "hookable": "^5.5.3", + "mitt": "^3.0.1", + "perfect-debounce": "^1.0.0", + "speakingurl": "^14.0.1", + "superjson": "^2.2.2" + } + }, + "node_modules/@vue/devtools-shared": { + "version": "7.7.7", + "resolved": "https://registry.npmjs.org/@vue/devtools-shared/-/devtools-shared-7.7.7.tgz", + "integrity": "sha512-+udSj47aRl5aKb0memBvcUG9koarqnxNM5yjuREvqwK6T3ap4mn3Zqqc17QrBFTqSMjr3HK1cvStEZpMDpfdyw==", + "dev": true, + "license": "MIT", + "dependencies": { + "rfdc": "^1.4.1" + } + }, + "node_modules/@vue/reactivity": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/reactivity/-/reactivity-3.5.17.tgz", + "integrity": "sha512-l/rmw2STIscWi7SNJp708FK4Kofs97zc/5aEPQh4bOsReD/8ICuBcEmS7KGwDj5ODQLYWVN2lNibKJL1z5b+Lw==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@vue/shared": "3.5.17" + } + }, + "node_modules/@vue/runtime-core": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/runtime-core/-/runtime-core-3.5.17.tgz", + "integrity": "sha512-QQLXa20dHg1R0ri4bjKeGFKEkJA7MMBxrKo2G+gJikmumRS7PTD4BOU9FKrDQWMKowz7frJJGqBffYMgQYS96Q==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@vue/reactivity": "3.5.17", + "@vue/shared": "3.5.17" + } + }, + "node_modules/@vue/runtime-dom": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/runtime-dom/-/runtime-dom-3.5.17.tgz", + "integrity": "sha512-8El0M60TcwZ1QMz4/os2MdlQECgGoVHPuLnQBU3m9h3gdNRW9xRmI8iLS4t/22OQlOE6aJvNNlBiCzPHur4H9g==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@vue/reactivity": "3.5.17", + "@vue/runtime-core": "3.5.17", + "@vue/shared": "3.5.17", + "csstype": "^3.1.3" + } + }, + "node_modules/@vue/server-renderer": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/server-renderer/-/server-renderer-3.5.17.tgz", + "integrity": "sha512-BOHhm8HalujY6lmC3DbqF6uXN/K00uWiEeF22LfEsm9Q93XeJ/plHTepGwf6tqFcF7GA5oGSSAAUock3VvzaCA==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-ssr": "3.5.17", + "@vue/shared": "3.5.17" + }, + "peerDependencies": { + "vue": "3.5.17" + } + }, + "node_modules/@vue/shared": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/@vue/shared/-/shared-3.5.17.tgz", + "integrity": "sha512-CabR+UN630VnsJO/jHWYBC1YVXyMq94KKp6iF5MQgZJs5I8cmjw6oVMO1oDbtBkENSHSSn/UadWlW/OAgdmKrg==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/@vueuse/core": { + "version": "12.8.2", + "resolved": "https://registry.npmjs.org/@vueuse/core/-/core-12.8.2.tgz", + "integrity": "sha512-HbvCmZdzAu3VGi/pWYm5Ut+Kd9mn1ZHnn4L5G8kOQTPs/IwIAmJoBrmYk2ckLArgMXZj0AW3n5CAejLUO+PhdQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/web-bluetooth": "^0.0.21", + "@vueuse/metadata": "12.8.2", + "@vueuse/shared": "12.8.2", + "vue": "^3.5.13" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/@vueuse/integrations": { + "version": "12.8.2", + "resolved": "https://registry.npmjs.org/@vueuse/integrations/-/integrations-12.8.2.tgz", + "integrity": "sha512-fbGYivgK5uBTRt7p5F3zy6VrETlV9RtZjBqd1/HxGdjdckBgBM4ugP8LHpjolqTj14TXTxSK1ZfgPbHYyGuH7g==", + "dev": true, + "license": "MIT", + "dependencies": { + "@vueuse/core": "12.8.2", + "@vueuse/shared": "12.8.2", + "vue": "^3.5.13" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + }, + "peerDependencies": { + "async-validator": "^4", + "axios": "^1", + "change-case": "^5", + "drauu": "^0.4", + "focus-trap": "^7", + "fuse.js": "^7", + "idb-keyval": "^6", + "jwt-decode": "^4", + "nprogress": "^0.2", + "qrcode": "^1.5", + "sortablejs": "^1", + "universal-cookie": "^7" + }, + "peerDependenciesMeta": { + "async-validator": { + "optional": true + }, + "axios": { + "optional": true + }, + "change-case": { + "optional": true + }, + "drauu": { + "optional": true + }, + "focus-trap": { + "optional": true + }, + "fuse.js": { + "optional": true + }, + "idb-keyval": { + "optional": true + }, + "jwt-decode": { + "optional": true + }, + "nprogress": { + "optional": true + }, + "qrcode": { + "optional": true + }, + "sortablejs": { + "optional": true + }, + "universal-cookie": { + "optional": true + } + } + }, + "node_modules/@vueuse/metadata": { + "version": "12.8.2", + "resolved": "https://registry.npmjs.org/@vueuse/metadata/-/metadata-12.8.2.tgz", + "integrity": "sha512-rAyLGEuoBJ/Il5AmFHiziCPdQzRt88VxR+Y/A/QhJ1EWtWqPBBAxTAFaSkviwEuOEZNtW8pvkPgoCZQ+HxqW1A==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/@vueuse/shared": { + "version": "12.8.2", + "resolved": "https://registry.npmjs.org/@vueuse/shared/-/shared-12.8.2.tgz", + "integrity": "sha512-dznP38YzxZoNloI0qpEfpkms8knDtaoQ6Y/sfS0L7Yki4zh40LFHEhur0odJC6xTHG5dxWVPiUWBXn+wCG2s5w==", + "dev": true, + "license": "MIT", + "dependencies": { + "vue": "^3.5.13" + }, + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/acorn": { + "version": "8.15.0", + "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz", + "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==", + "dev": true, + "license": "MIT", + "bin": { + "acorn": "bin/acorn" + }, + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/algoliasearch": { + "version": "5.32.0", + "resolved": "https://registry.npmjs.org/algoliasearch/-/algoliasearch-5.32.0.tgz", + "integrity": "sha512-84xBncKNPBK8Ae89F65+SyVcOihrIbm/3N7to+GpRBHEUXGjA3ydWTMpcRW6jmFzkBQ/eqYy/y+J+NBpJWYjBg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@algolia/client-abtesting": "5.32.0", + "@algolia/client-analytics": "5.32.0", + "@algolia/client-common": "5.32.0", + "@algolia/client-insights": "5.32.0", + "@algolia/client-personalization": "5.32.0", + "@algolia/client-query-suggestions": "5.32.0", + "@algolia/client-search": "5.32.0", + "@algolia/ingestion": "1.32.0", + "@algolia/monitoring": "1.32.0", + "@algolia/recommend": "5.32.0", + "@algolia/requester-browser-xhr": "5.32.0", + "@algolia/requester-fetch": "5.32.0", + "@algolia/requester-node-http": "5.32.0" + }, + "engines": { + "node": ">= 14.0.0" + } + }, + "node_modules/arg": { + "version": "5.0.2", + "resolved": "https://registry.npmjs.org/arg/-/arg-5.0.2.tgz", + "integrity": "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==", + "license": "MIT" + }, + "node_modules/birpc": { + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/birpc/-/birpc-2.4.0.tgz", + "integrity": "sha512-5IdNxTyhXHv2UlgnPHQ0h+5ypVmkrYHzL8QT+DwFZ//2N/oNV8Ch+BCRmTJ3x6/z9Axo/cXYBc9eprsUVK/Jsg==", + "dev": true, + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/antfu" + } + }, + "node_modules/buffer-from": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/buffer-from/-/buffer-from-1.1.2.tgz", + "integrity": "sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/ccount": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/ccount/-/ccount-2.0.1.tgz", + "integrity": "sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/character-entities/-/character-entities-2.0.2.tgz", + "integrity": "sha512-shx7oQ0Awen/BRIdkjkvz54PnEEI/EjwXDSIZp86/KKdbafHh1Df/RYGBhn4hbe2+uKC9FnT5UCEdyPz3ai9hQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-html4": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/character-entities-html4/-/character-entities-html4-2.1.0.tgz", + "integrity": "sha512-1v7fgQRj6hnSwFpq1Eu0ynr/CDEw0rXo2B61qXrLNdHZmPKgb7fqS1a2JwF0rISo9q77jDI8VMEHoApn8qDoZA==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/character-entities-legacy": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/character-entities-legacy/-/character-entities-legacy-3.0.0.tgz", + "integrity": "sha512-RpPp0asT/6ufRm//AJVwpViZbGM/MkjQFxJccQRHmISF/22NBtsHqAWmL+/pmkPWoIUJdWyeVleTl1wydHATVQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/comma-separated-tokens": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/comma-separated-tokens/-/comma-separated-tokens-2.0.3.tgz", + "integrity": "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/commander": { + "version": "7.2.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-7.2.0.tgz", + "integrity": "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 10" + } + }, + "node_modules/copy-anything": { + "version": "3.0.5", + "resolved": "https://registry.npmjs.org/copy-anything/-/copy-anything-3.0.5.tgz", + "integrity": "sha512-yCEafptTtb4bk7GLEQoM8KVJpxAfdBJYaXyzQEgQQQgYrZiDp8SJmGKlYza6CYjEDNstAdNdKA3UuoULlEbS6w==", + "dev": true, + "license": "MIT", + "dependencies": { + "is-what": "^4.1.8" + }, + "engines": { + "node": ">=12.13" + }, + "funding": { + "url": "https://github.com/sponsors/mesqueeb" + } + }, + "node_modules/cose-base": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-1.0.3.tgz", + "integrity": "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg==", + "dev": true, + "license": "MIT", + "dependencies": { + "layout-base": "^1.0.0" + } + }, + "node_modules/csstype": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz", + "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/cytoscape": { + "version": "3.32.1", + "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.32.1.tgz", + "integrity": "sha512-dbeqFTLYEwlFg7UGtcZhCCG/2WayX72zK3Sq323CEX29CY81tYfVhw1MIdduCtpstB0cTOhJswWlM/OEB3Xp+Q==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.10" + } + }, + "node_modules/cytoscape-cose-bilkent": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/cytoscape-cose-bilkent/-/cytoscape-cose-bilkent-4.1.0.tgz", + "integrity": "sha512-wgQlVIUJF13Quxiv5e1gstZ08rnZj2XaLHGoFMYXz7SkNfCDOOteKBE6SYRfA9WxxI/iBc3ajfDoc6hb/MRAHQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "cose-base": "^1.0.0" + }, + "peerDependencies": { + "cytoscape": "^3.2.0" + } + }, + "node_modules/cytoscape-fcose": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/cytoscape-fcose/-/cytoscape-fcose-2.2.0.tgz", + "integrity": "sha512-ki1/VuRIHFCzxWNrsshHYPs6L7TvLu3DL+TyIGEsRcvVERmxokbf5Gdk7mFxZnTdiGtnA4cfSmjZJMviqSuZrQ==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "cose-base": "^2.2.0" + }, + "peerDependencies": { + "cytoscape": "^3.2.0" + } + }, + "node_modules/cytoscape-fcose/node_modules/cose-base": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/cose-base/-/cose-base-2.2.0.tgz", + "integrity": "sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g==", + "dev": true, + "license": "MIT", + "optional": true, + "dependencies": { + "layout-base": "^2.0.0" + } + }, + "node_modules/cytoscape-fcose/node_modules/layout-base": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-2.0.1.tgz", + "integrity": "sha512-dp3s92+uNI1hWIpPGH3jK2kxE2lMjdXdr+DH8ynZHpd6PUlH6x6cbuXnoMmiNumznqaNO31xu9e79F0uuZ0JFg==", + "dev": true, + "license": "MIT", + "optional": true + }, + "node_modules/d3": { + "version": "7.9.0", + "resolved": "https://registry.npmjs.org/d3/-/d3-7.9.0.tgz", + "integrity": "sha512-e1U46jVP+w7Iut8Jt8ri1YsPOvFpg46k+K8TpCb0P+zjCkjkPnV7WzfDJzMHy1LnA+wj5pLT1wjO901gLXeEhA==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-array": "3", + "d3-axis": "3", + "d3-brush": "3", + "d3-chord": "3", + "d3-color": "3", + "d3-contour": "4", + "d3-delaunay": "6", + "d3-dispatch": "3", + "d3-drag": "3", + "d3-dsv": "3", + "d3-ease": "3", + "d3-fetch": "3", + "d3-force": "3", + "d3-format": "3", + "d3-geo": "3", + "d3-hierarchy": "3", + "d3-interpolate": "3", + "d3-path": "3", + "d3-polygon": "3", + "d3-quadtree": "3", + "d3-random": "3", + "d3-scale": "4", + "d3-scale-chromatic": "3", + "d3-selection": "3", + "d3-shape": "3", + "d3-time": "3", + "d3-time-format": "4", + "d3-timer": "3", + "d3-transition": "3", + "d3-zoom": "3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-array": { + "version": "3.2.4", + "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-3.2.4.tgz", + "integrity": "sha512-tdQAmyA18i4J7wprpYq8ClcxZy3SC31QMeByyCFyRt7BVHdREQZ5lpzoe5mFEYZUWe+oq8HBvk9JjpibyEV4Jg==", + "dev": true, + "license": "ISC", + "dependencies": { + "internmap": "1 - 2" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-axis": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-axis/-/d3-axis-3.0.0.tgz", + "integrity": "sha512-IH5tgjV4jE/GhHkRV0HiVYPDtvfjHQlQfJHs0usq7M30XcSBvOotpmH1IgkcXsO/5gEQZD43B//fc7SRT5S+xw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-brush": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-brush/-/d3-brush-3.0.0.tgz", + "integrity": "sha512-ALnjWlVYkXsVIGlOsuWH1+3udkYFI48Ljihfnh8FZPF2QS9o+PzGLBslO0PjzVoHLZ2KCVgAM8NVkXPJB2aNnQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-drag": "2 - 3", + "d3-interpolate": "1 - 3", + "d3-selection": "3", + "d3-transition": "3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-chord": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-chord/-/d3-chord-3.0.1.tgz", + "integrity": "sha512-VE5S6TNa+j8msksl7HwjxMHDM2yNK3XCkusIlpX5kwauBfXuyLAtNg9jCp/iHH61tgI4sb6R/EIMWCqEIdjT/g==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-path": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-color": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-color/-/d3-color-3.1.0.tgz", + "integrity": "sha512-zg/chbXyeBtMQ1LbD/WSoW2DpC3I0mpmPdW+ynRTj/x2DAWYrIY7qeZIHidozwV24m4iavr15lNwIwLxRmOxhA==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-contour": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/d3-contour/-/d3-contour-4.0.2.tgz", + "integrity": "sha512-4EzFTRIikzs47RGmdxbeUvLWtGedDUNkTcmzoeyg4sP/dvCexO47AaQL7VKy/gul85TOxw+IBgA8US2xwbToNA==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-array": "^3.2.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-delaunay": { + "version": "6.0.4", + "resolved": "https://registry.npmjs.org/d3-delaunay/-/d3-delaunay-6.0.4.tgz", + "integrity": "sha512-mdjtIZ1XLAM8bm/hx3WwjfHt6Sggek7qH043O8KEjDXN40xi3vx/6pYSVTwLjEgiXQTbvaouWKynLBiUZ6SK6A==", + "dev": true, + "license": "ISC", + "dependencies": { + "delaunator": "5" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-dispatch": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-dispatch/-/d3-dispatch-3.0.1.tgz", + "integrity": "sha512-rzUyPU/S7rwUflMyLc1ETDeBj0NRuHKKAcvukozwhshr6g6c5d8zh4c2gQjY2bZ0dXeGLWc1PF174P2tVvKhfg==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-drag": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-drag/-/d3-drag-3.0.0.tgz", + "integrity": "sha512-pWbUJLdETVA8lQNJecMxoXfH6x+mO2UQo8rSmZ+QqxcbyA3hfeprFgIT//HW2nlHChWeIIMwS2Fq+gEARkhTkg==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-selection": "3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-dsv": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-dsv/-/d3-dsv-3.0.1.tgz", + "integrity": "sha512-UG6OvdI5afDIFP9w4G0mNq50dSOsXHJaRE8arAS5o9ApWnIElp8GZw1Dun8vP8OyHOZ/QJUKUJwxiiCCnUwm+Q==", + "dev": true, + "license": "ISC", + "dependencies": { + "commander": "7", + "iconv-lite": "0.6", + "rw": "1" + }, + "bin": { + "csv2json": "bin/dsv2json.js", + "csv2tsv": "bin/dsv2dsv.js", + "dsv2dsv": "bin/dsv2dsv.js", + "dsv2json": "bin/dsv2json.js", + "json2csv": "bin/json2dsv.js", + "json2dsv": "bin/json2dsv.js", + "json2tsv": "bin/json2dsv.js", + "tsv2csv": "bin/dsv2dsv.js", + "tsv2json": "bin/dsv2json.js" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-ease": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-ease/-/d3-ease-3.0.1.tgz", + "integrity": "sha512-wR/XK3D3XcLIZwpbvQwQ5fK+8Ykds1ip7A2Txe0yxncXSdq1L9skcG7blcedkOX+ZcgxGAmLX1FrRGbADwzi0w==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-fetch": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-fetch/-/d3-fetch-3.0.1.tgz", + "integrity": "sha512-kpkQIM20n3oLVBKGg6oHrUchHM3xODkTzjMoj7aWQFq5QEM+R6E4WkzT5+tojDY7yjez8KgCBRoj4aEr99Fdqw==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-dsv": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-force": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-force/-/d3-force-3.0.0.tgz", + "integrity": "sha512-zxV/SsA+U4yte8051P4ECydjD/S+qeYtnaIyAs9tgHCqfguma/aAQDjo85A9Z6EKhBirHRJHXIgJUlffT4wdLg==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-quadtree": "1 - 3", + "d3-timer": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-format": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-format/-/d3-format-3.1.0.tgz", + "integrity": "sha512-YyUI6AEuY/Wpt8KWLgZHsIU86atmikuoOmCfommt0LYHiQSPjvX2AcFc38PX0CBpr2RCyZhjex+NS/LPOv6YqA==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-geo": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/d3-geo/-/d3-geo-3.1.1.tgz", + "integrity": "sha512-637ln3gXKXOwhalDzinUgY83KzNWZRKbYubaG+fGVuc/dxO64RRljtCTnf5ecMyE1RIdtqpkVcq0IbtU2S8j2Q==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-array": "2.5.0 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-hierarchy": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/d3-hierarchy/-/d3-hierarchy-3.1.2.tgz", + "integrity": "sha512-FX/9frcub54beBdugHjDCdikxThEqjnR93Qt7PvQTOHxyiNCAlvMrHhclk3cD5VeAaq9fxmfRp+CnWw9rEMBuA==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-interpolate": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-interpolate/-/d3-interpolate-3.0.1.tgz", + "integrity": "sha512-3bYs1rOD33uo8aqJfKP3JWPAibgw8Zm2+L9vBKEHJ2Rg+viTR7o5Mmv5mZcieN+FRYaAOWX5SJATX6k1PWz72g==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-color": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-path": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-3.1.0.tgz", + "integrity": "sha512-p3KP5HCf/bvjBSSKuXid6Zqijx7wIfNW+J/maPs+iwR35at5JCbLUT0LzF1cnjbCHWhqzQTIN2Jpe8pRebIEFQ==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-polygon": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-polygon/-/d3-polygon-3.0.1.tgz", + "integrity": "sha512-3vbA7vXYwfe1SYhED++fPUQlWSYTTGmFmQiany/gdbiWgU/iEyQzyymwL9SkJjFFuCS4902BSzewVGsHHmHtXg==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-quadtree": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-quadtree/-/d3-quadtree-3.0.1.tgz", + "integrity": "sha512-04xDrxQTDTCFwP5H6hRhsRcb9xxv2RzkcsygFzmkSIOJy3PeRJP7sNk3VRIbKXcog561P9oU0/rVH6vDROAgUw==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-random": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-random/-/d3-random-3.0.1.tgz", + "integrity": "sha512-FXMe9GfxTxqd5D6jFsQ+DJ8BJS4E/fT5mqqdjovykEB2oFbTMDVdg1MGFxfQW+FBOGoB++k8swBrgwSHT1cUXQ==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-sankey": { + "version": "0.12.3", + "resolved": "https://registry.npmjs.org/d3-sankey/-/d3-sankey-0.12.3.tgz", + "integrity": "sha512-nQhsBRmM19Ax5xEIPLMY9ZmJ/cDvd1BG3UVvt5h3WRxKg5zGRbvnteTyWAbzeSvlh3tW7ZEmq4VwR5mB3tutmQ==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "d3-array": "1 - 2", + "d3-shape": "^1.2.0" + } + }, + "node_modules/d3-sankey/node_modules/d3-array": { + "version": "2.12.1", + "resolved": "https://registry.npmjs.org/d3-array/-/d3-array-2.12.1.tgz", + "integrity": "sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "internmap": "^1.0.0" + } + }, + "node_modules/d3-sankey/node_modules/d3-path": { + "version": "1.0.9", + "resolved": "https://registry.npmjs.org/d3-path/-/d3-path-1.0.9.tgz", + "integrity": "sha512-VLaYcn81dtHVTjEHd8B+pbe9yHWpXKZUC87PzoFmsFrJqgFwDe/qxfp5MlfsfM1V5E/iVt0MmEbWQ7FVIXh/bg==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/d3-sankey/node_modules/d3-shape": { + "version": "1.3.7", + "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-1.3.7.tgz", + "integrity": "sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw==", + "dev": true, + "license": "BSD-3-Clause", + "dependencies": { + "d3-path": "1" + } + }, + "node_modules/d3-sankey/node_modules/internmap": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/internmap/-/internmap-1.0.1.tgz", + "integrity": "sha512-lDB5YccMydFBtasVtxnZ3MRBHuaoE8GKsppq+EchKL2U4nK/DmEpPHNH8MZe5HkMtpSiTSOZwfN0tzYjO/lJEw==", + "dev": true, + "license": "ISC" + }, + "node_modules/d3-scale": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/d3-scale/-/d3-scale-4.0.2.tgz", + "integrity": "sha512-GZW464g1SH7ag3Y7hXjf8RoUuAFIqklOAq3MRl4OaWabTFJY9PN/E1YklhXLh+OQ3fM9yS2nOkCoS+WLZ6kvxQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-array": "2.10.0 - 3", + "d3-format": "1 - 3", + "d3-interpolate": "1.2.0 - 3", + "d3-time": "2.1.1 - 3", + "d3-time-format": "2 - 4" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-scale-chromatic": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-scale-chromatic/-/d3-scale-chromatic-3.1.0.tgz", + "integrity": "sha512-A3s5PWiZ9YCXFye1o246KoscMWqf8BsD9eRiJ3He7C9OBaxKhAd5TFCdEx/7VbKtxxTsu//1mMJFrEt572cEyQ==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-color": "1 - 3", + "d3-interpolate": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-selection": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-selection/-/d3-selection-3.0.0.tgz", + "integrity": "sha512-fmTRWbNMmsmWq6xJV8D19U/gw/bwrHfNXxrIN+HfZgnzqTHp9jOmKMhsTUjXOJnZOdZY9Q28y4yebKzqDKlxlQ==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-shape": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/d3-shape/-/d3-shape-3.2.0.tgz", + "integrity": "sha512-SaLBuwGm3MOViRq2ABk3eLoxwZELpH6zhl3FbAoJ7Vm1gofKx6El1Ib5z23NUEhF9AsGl7y+dzLe5Cw2AArGTA==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-path": "^3.1.0" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-time": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/d3-time/-/d3-time-3.1.0.tgz", + "integrity": "sha512-VqKjzBLejbSMT4IgbmVgDjpkYrNWUYJnbCGo874u7MMKIWsILRX+OpX/gTk8MqjpT1A/c6HY2dCA77ZN0lkQ2Q==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-array": "2 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-time-format": { + "version": "4.1.0", + "resolved": "https://registry.npmjs.org/d3-time-format/-/d3-time-format-4.1.0.tgz", + "integrity": "sha512-dJxPBlzC7NugB2PDLwo9Q8JiTR3M3e4/XANkreKSUxF8vvXKqm1Yfq4Q5dl8budlunRVlUUaDUgFt7eA8D6NLg==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-time": "1 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-timer": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-timer/-/d3-timer-3.0.1.tgz", + "integrity": "sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/d3-transition": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/d3-transition/-/d3-transition-3.0.1.tgz", + "integrity": "sha512-ApKvfjsSR6tg06xrL434C0WydLr7JewBB3V+/39RMHsaXTOG0zmt/OAXeng5M5LBm0ojmxJrpomQVZ1aPvBL4w==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-color": "1 - 3", + "d3-dispatch": "1 - 3", + "d3-ease": "1 - 3", + "d3-interpolate": "1 - 3", + "d3-timer": "1 - 3" + }, + "engines": { + "node": ">=12" + }, + "peerDependencies": { + "d3-selection": "2 - 3" + } + }, + "node_modules/d3-zoom": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/d3-zoom/-/d3-zoom-3.0.0.tgz", + "integrity": "sha512-b8AmV3kfQaqWAuacbPuNbL6vahnOJflOhexLzMMNLga62+/nh0JzvJ0aO/5a5MVgUFGS7Hu1P9P03o3fJkDCyw==", + "dev": true, + "license": "ISC", + "dependencies": { + "d3-dispatch": "1 - 3", + "d3-drag": "2 - 3", + "d3-interpolate": "1 - 3", + "d3-selection": "2 - 3", + "d3-transition": "2 - 3" + }, + "engines": { + "node": ">=12" + } + }, + "node_modules/dagre-d3-es": { + "version": "7.0.10", + "resolved": "https://registry.npmjs.org/dagre-d3-es/-/dagre-d3-es-7.0.10.tgz", + "integrity": "sha512-qTCQmEhcynucuaZgY5/+ti3X/rnszKZhEQH/ZdWdtP1tA/y3VoHJzcVrO9pjjJCNpigfscAtoUB5ONcd2wNn0A==", + "dev": true, + "license": "MIT", + "dependencies": { + "d3": "^7.8.2", + "lodash-es": "^4.17.21" + } + }, + "node_modules/dayjs": { + "version": "1.11.13", + "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.13.tgz", + "integrity": "sha512-oaMBel6gjolK862uaPQOVTA7q3TZhuSvuMQAAglQDOWYO9A91IrAOUJEyKVlqJlHE0vq5p5UXxzdPfMH/x6xNg==", + "dev": true, + "license": "MIT" + }, + "node_modules/debug": { + "version": "4.4.1", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.1.tgz", + "integrity": "sha512-KcKCqiftBJcZr++7ykoDIEwSa3XWowTfNPo92BYxjXiyYEVrUQh2aLyhxBCwww+heortUFxEJYcRzosstTEBYQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/decode-named-character-reference": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/decode-named-character-reference/-/decode-named-character-reference-1.2.0.tgz", + "integrity": "sha512-c6fcElNV6ShtZXmsgNgFFV5tVX2PaV4g+MOAkb8eXHvn6sryJBrZa9r0zV6+dtTyoCKxtDy5tyQ5ZwQuidtd+Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "character-entities": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/delaunator": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/delaunator/-/delaunator-5.0.1.tgz", + "integrity": "sha512-8nvh+XBe96aCESrGOqMp/84b13H9cdKbG5P2ejQCh4d4sK9RL4371qou9drQjMhvnPmhWl5hnmqbEE0fXr9Xnw==", + "dev": true, + "license": "ISC", + "dependencies": { + "robust-predicates": "^3.0.2" + } + }, + "node_modules/dequal": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/dequal/-/dequal-2.0.3.tgz", + "integrity": "sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/devlop": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/devlop/-/devlop-1.1.0.tgz", + "integrity": "sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==", + "dev": true, + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/diff": { + "version": "5.2.0", + "resolved": "https://registry.npmjs.org/diff/-/diff-5.2.0.tgz", + "integrity": "sha512-uIFDxqpRZGZ6ThOk84hEfqWoHx2devRFvpTZcTHur85vImfaxUbTW9Ryh4CpCuDnToOP1CEtXKIgytHBPVff5A==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.3.1" + } + }, + "node_modules/dompurify": { + "version": "3.1.6", + "resolved": "https://registry.npmjs.org/dompurify/-/dompurify-3.1.6.tgz", + "integrity": "sha512-cTOAhc36AalkjtBpfG6O8JimdTMWNXjiePT2xQH/ppBGi/4uIpmj8eKyIkMJErXWARyINV/sB38yf8JCLF5pbQ==", + "dev": true, + "license": "(MPL-2.0 OR Apache-2.0)" + }, + "node_modules/elkjs": { + "version": "0.9.3", + "resolved": "https://registry.npmjs.org/elkjs/-/elkjs-0.9.3.tgz", + "integrity": "sha512-f/ZeWvW/BCXbhGEf1Ujp29EASo/lk1FDnETgNKwJrsVvGZhUWCZyg3xLJjAsxfOmt8KjswHmI5EwCQcPMpOYhQ==", + "dev": true, + "license": "EPL-2.0" + }, + "node_modules/emoji-regex-xs": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/emoji-regex-xs/-/emoji-regex-xs-1.0.0.tgz", + "integrity": "sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==", + "dev": true, + "license": "MIT" + }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "devOptional": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, + "node_modules/esbuild": { + "version": "0.21.5", + "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.21.5.tgz", + "integrity": "sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "bin": { + "esbuild": "bin/esbuild" + }, + "engines": { + "node": ">=12" + }, + "optionalDependencies": { + "@esbuild/aix-ppc64": "0.21.5", + "@esbuild/android-arm": "0.21.5", + "@esbuild/android-arm64": "0.21.5", + "@esbuild/android-x64": "0.21.5", + "@esbuild/darwin-arm64": "0.21.5", + "@esbuild/darwin-x64": "0.21.5", + "@esbuild/freebsd-arm64": "0.21.5", + "@esbuild/freebsd-x64": "0.21.5", + "@esbuild/linux-arm": "0.21.5", + "@esbuild/linux-arm64": "0.21.5", + "@esbuild/linux-ia32": "0.21.5", + "@esbuild/linux-loong64": "0.21.5", + "@esbuild/linux-mips64el": "0.21.5", + "@esbuild/linux-ppc64": "0.21.5", + "@esbuild/linux-riscv64": "0.21.5", + "@esbuild/linux-s390x": "0.21.5", + "@esbuild/linux-x64": "0.21.5", + "@esbuild/netbsd-x64": "0.21.5", + "@esbuild/openbsd-x64": "0.21.5", + "@esbuild/sunos-x64": "0.21.5", + "@esbuild/win32-arm64": "0.21.5", + "@esbuild/win32-ia32": "0.21.5", + "@esbuild/win32-x64": "0.21.5" + } + }, + "node_modules/estree-walker": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/estree-walker/-/estree-walker-2.0.2.tgz", + "integrity": "sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==", + "devOptional": true, + "license": "MIT" + }, + "node_modules/focus-trap": { + "version": "7.6.5", + "resolved": "https://registry.npmjs.org/focus-trap/-/focus-trap-7.6.5.tgz", + "integrity": "sha512-7Ke1jyybbbPZyZXFxEftUtxFGLMpE2n6A+z//m4CRDlj0hW+o3iYSmh8nFlYMurOiJVDmJRilUQtJr08KfIxlg==", + "dev": true, + "license": "MIT", + "dependencies": { + "tabbable": "^6.2.0" + } + }, + "node_modules/fsevents": { + "version": "2.3.3", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz", + "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, + "node_modules/hast-util-to-html": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/hast-util-to-html/-/hast-util-to-html-9.0.5.tgz", + "integrity": "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/unist": "^3.0.0", + "ccount": "^2.0.0", + "comma-separated-tokens": "^2.0.0", + "hast-util-whitespace": "^3.0.0", + "html-void-elements": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "property-information": "^7.0.0", + "space-separated-tokens": "^2.0.0", + "stringify-entities": "^4.0.0", + "zwitch": "^2.0.4" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hast-util-to-html/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/hast-util-whitespace": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/hast-util-whitespace/-/hast-util-whitespace-3.0.0.tgz", + "integrity": "sha512-88JUN06ipLwsnv+dVn+OIYOvAuvBMy/Qoi6O7mQHxdPXpjy+Cd6xRkWwux7DKO+4sYILtLBRIKgsdpS2gQc7qw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/hookable": { + "version": "5.5.3", + "resolved": "https://registry.npmjs.org/hookable/-/hookable-5.5.3.tgz", + "integrity": "sha512-Yc+BQe8SvoXH1643Qez1zqLRmbA5rCL+sSmk6TVos0LWVfNIB7PGncdlId77WzLGSIB5KaWgTaNTs2lNVEI6VQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/html-void-elements": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/html-void-elements/-/html-void-elements-3.0.0.tgz", + "integrity": "sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/iconv-lite": { + "version": "0.6.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz", + "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==", + "dev": true, + "license": "MIT", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/internmap": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/internmap/-/internmap-2.0.3.tgz", + "integrity": "sha512-5Hh7Y1wQbvY5ooGgPbDaL5iYLAPzMTUrjMulskHLH6wnv/A+1q5rgEaiuqEjB+oxGXIVZs1FF+R/KPN3ZSQYYg==", + "dev": true, + "license": "ISC", + "engines": { + "node": ">=12" + } + }, + "node_modules/is-what": { + "version": "4.1.16", + "resolved": "https://registry.npmjs.org/is-what/-/is-what-4.1.16.tgz", + "integrity": "sha512-ZhMwEosbFJkA0YhFnNDgTM4ZxDRsS6HqTo7qsZM08fehyRYIYa0yHu5R6mgo1n/8MgaPBXiPimPD77baVFYg+A==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=12.13" + }, + "funding": { + "url": "https://github.com/sponsors/mesqueeb" + } + }, + "node_modules/katex": { + "version": "0.16.22", + "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.22.tgz", + "integrity": "sha512-XCHRdUw4lf3SKBaJe4EvgqIuWwkPSo9XoeO8GjQW94Bp7TWv9hNhzZjZ+OH9yf1UmLygb7DIT5GSFQiyt16zYg==", + "dev": true, + "funding": [ + "https://opencollective.com/katex", + "https://github.com/sponsors/katex" + ], + "license": "MIT", + "dependencies": { + "commander": "^8.3.0" + }, + "bin": { + "katex": "cli.js" + } + }, + "node_modules/katex/node_modules/commander": { + "version": "8.3.0", + "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz", + "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/khroma": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/khroma/-/khroma-2.1.0.tgz", + "integrity": "sha512-Ls993zuzfayK269Svk9hzpeGUKob/sIgZzyHYdjQoAdQetRKpOLj+k/QQQ/6Qi0Yz65mlROrfd+Ev+1+7dz9Kw==", + "dev": true + }, + "node_modules/kleur": { + "version": "4.1.5", + "resolved": "https://registry.npmjs.org/kleur/-/kleur-4.1.5.tgz", + "integrity": "sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, + "node_modules/layout-base": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/layout-base/-/layout-base-1.0.2.tgz", + "integrity": "sha512-8h2oVEZNktL4BH2JCOI90iD1yXwL6iNW7KcCKT2QZgQJR2vbqDsldCTPRU9NifTCqHZci57XvQQ15YTu+sTYPg==", + "dev": true, + "license": "MIT" + }, + "node_modules/lodash": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", + "integrity": "sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==", + "license": "MIT" + }, + "node_modules/lodash-es": { + "version": "4.17.21", + "resolved": "https://registry.npmjs.org/lodash-es/-/lodash-es-4.17.21.tgz", + "integrity": "sha512-mKnC+QJ9pWVzv+C4/U3rRsHapFfHvQFoFB92e52xeyGMcX6/OlIl78je1u8vePzYZSkkogMPJ2yjxxsb89cxyw==", + "dev": true, + "license": "MIT" + }, + "node_modules/magic-string": { + "version": "0.30.17", + "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.17.tgz", + "integrity": "sha512-sNPKHvyjVf7gyjwS4xGTaW/mCnF8wnjtifKBEhxfZ7E/S8tQ0rssrwGNn6q8JH/ohItJfSQp9mBtQYuTlH5QnA==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@jridgewell/sourcemap-codec": "^1.5.0" + } + }, + "node_modules/mark.js": { + "version": "8.11.1", + "resolved": "https://registry.npmjs.org/mark.js/-/mark.js-8.11.1.tgz", + "integrity": "sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/mdast-util-from-markdown": { + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/mdast-util-from-markdown/-/mdast-util-from-markdown-1.3.1.tgz", + "integrity": "sha512-4xTO/M8c82qBcnQc1tgpNtubGUW/Y1tBQ1B0i5CtSoelOLKFYlElIr3bvgREYYO5iRqbMY1YuqZng0GVOI8Qww==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^3.0.0", + "@types/unist": "^2.0.0", + "decode-named-character-reference": "^1.0.0", + "mdast-util-to-string": "^3.1.0", + "micromark": "^3.0.0", + "micromark-util-decode-numeric-character-reference": "^1.0.0", + "micromark-util-decode-string": "^1.0.0", + "micromark-util-normalize-identifier": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0", + "unist-util-stringify-position": "^3.0.0", + "uvu": "^0.5.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-hast": { + "version": "13.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-hast/-/mdast-util-to-hast-13.2.0.tgz", + "integrity": "sha512-QGYKEuUsYT9ykKBCMOEDLsU5JRObWQusAolFMeko/tYPufNkRffBAQjIE+99jbA87xv6FgmjLtwjh9wBWajwAA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "@ungap/structured-clone": "^1.0.0", + "devlop": "^1.0.0", + "micromark-util-sanitize-uri": "^2.0.0", + "trim-lines": "^3.0.0", + "unist-util-position": "^5.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/mdast-util-to-hast/node_modules/@types/mdast": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/@types/mdast/-/mdast-4.0.4.tgz", + "integrity": "sha512-kGaNbPh1k7AFzgpud/gMdvIm5xuECykRR+JnWKQno9TAXVa6WIVCGTPvYGekIDL4uwCZQSYbUxNBSb1aUo79oA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, + "node_modules/mdast-util-to-hast/node_modules/micromark-util-character": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-2.1.1.tgz", + "integrity": "sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^2.0.0", + "micromark-util-types": "^2.0.0" + } + }, + "node_modules/mdast-util-to-hast/node_modules/micromark-util-encode": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-2.0.1.tgz", + "integrity": "sha512-c3cVx2y4KqUnwopcO9b/SCdo2O67LwJJ/UyqGfbigahfegL9myoEFoDYZgkT7f36T0bLrM9hZTAaAyH+PCAXjw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/mdast-util-to-hast/node_modules/micromark-util-sanitize-uri": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-2.0.1.tgz", + "integrity": "sha512-9N9IomZ/YuGGZZmQec1MbgxtlgougxTodVwDzzEouPKo3qFWvymFHWcnDi2vzV1ff6kas9ucW+o3yzJK9YB1AQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^2.0.0", + "micromark-util-encode": "^2.0.0", + "micromark-util-symbol": "^2.0.0" + } + }, + "node_modules/mdast-util-to-hast/node_modules/micromark-util-symbol": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-2.0.1.tgz", + "integrity": "sha512-vs5t8Apaud9N28kgCrRUdEed4UJ+wWNvicHLPxCa9ENlYuAY31M0ETy5y1vA33YoNPDFTghEbnh6efaE8h4x0Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/mdast-util-to-hast/node_modules/micromark-util-types": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-2.0.2.tgz", + "integrity": "sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/mdast-util-to-string": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/mdast-util-to-string/-/mdast-util-to-string-3.2.0.tgz", + "integrity": "sha512-V4Zn/ncyN1QNSqSBxTrMOLpjr+IKdHl2v3KVLoWmDPscP4r9GcCi71gjgvUV1SFSKh92AjAG4peFuBl2/YgCJg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/mdast": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/medium-zoom": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/medium-zoom/-/medium-zoom-1.1.0.tgz", + "integrity": "sha512-ewyDsp7k4InCUp3jRmwHBRFGyjBimKps/AJLjRSox+2q/2H4p/PNpQf+pwONWlJiOudkBXtbdmVbFjqyybfTmQ==", + "license": "MIT" + }, + "node_modules/mermaid": { + "version": "10.9.3", + "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-10.9.3.tgz", + "integrity": "sha512-V80X1isSEvAewIL3xhmz/rVmc27CVljcsbWxkxlWJWY/1kQa4XOABqpDl2qQLGKzpKm6WbTfUEKImBlUfFYArw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@braintree/sanitize-url": "^6.0.1", + "@types/d3-scale": "^4.0.3", + "@types/d3-scale-chromatic": "^3.0.0", + "cytoscape": "^3.28.1", + "cytoscape-cose-bilkent": "^4.1.0", + "d3": "^7.4.0", + "d3-sankey": "^0.12.3", + "dagre-d3-es": "7.0.10", + "dayjs": "^1.11.7", + "dompurify": "^3.0.5 <3.1.7", + "elkjs": "^0.9.0", + "katex": "^0.16.9", + "khroma": "^2.0.0", + "lodash-es": "^4.17.21", + "mdast-util-from-markdown": "^1.3.0", + "non-layered-tidy-tree-layout": "^2.0.2", + "stylis": "^4.1.3", + "ts-dedent": "^2.2.0", + "uuid": "^9.0.0", + "web-worker": "^1.2.0" + } + }, + "node_modules/micromark": { + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/micromark/-/micromark-3.2.0.tgz", + "integrity": "sha512-uD66tJj54JLYq0De10AhWycZWGQNUvDI55xPgk2sQM5kn1JYlhbCMTtEeT27+vAhW2FBQxLlOmS3pmA7/2z4aA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "@types/debug": "^4.0.0", + "debug": "^4.0.0", + "decode-named-character-reference": "^1.0.0", + "micromark-core-commonmark": "^1.0.1", + "micromark-factory-space": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-chunked": "^1.0.0", + "micromark-util-combine-extensions": "^1.0.0", + "micromark-util-decode-numeric-character-reference": "^1.0.0", + "micromark-util-encode": "^1.0.0", + "micromark-util-normalize-identifier": "^1.0.0", + "micromark-util-resolve-all": "^1.0.0", + "micromark-util-sanitize-uri": "^1.0.0", + "micromark-util-subtokenize": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.1", + "uvu": "^0.5.0" + } + }, + "node_modules/micromark-core-commonmark": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-core-commonmark/-/micromark-core-commonmark-1.1.0.tgz", + "integrity": "sha512-BgHO1aRbolh2hcrzL2d1La37V0Aoz73ymF8rAcKnohLy93titmv62E0gP8Hrx9PKcKrqCZ1BbLGbP3bEhoXYlw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-factory-destination": "^1.0.0", + "micromark-factory-label": "^1.0.0", + "micromark-factory-space": "^1.0.0", + "micromark-factory-title": "^1.0.0", + "micromark-factory-whitespace": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-chunked": "^1.0.0", + "micromark-util-classify-character": "^1.0.0", + "micromark-util-html-tag-name": "^1.0.0", + "micromark-util-normalize-identifier": "^1.0.0", + "micromark-util-resolve-all": "^1.0.0", + "micromark-util-subtokenize": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.1", + "uvu": "^0.5.0" + } + }, + "node_modules/micromark-factory-destination": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-destination/-/micromark-factory-destination-1.1.0.tgz", + "integrity": "sha512-XaNDROBgx9SgSChd69pjiGKbV+nfHGDPVYFs5dOoDd7ZnMAE+Cuu91BCpsY8RT2NP9vo/B8pds2VQNCLiu0zhg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-factory-label": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-label/-/micromark-factory-label-1.1.0.tgz", + "integrity": "sha512-OLtyez4vZo/1NjxGhcpDSbHQ+m0IIGnT8BoPamh+7jVlzLJBH98zzuCoUeMxvM6WsNeh8wx8cKvqLiPHEACn0w==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0", + "uvu": "^0.5.0" + } + }, + "node_modules/micromark-factory-space": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-space/-/micromark-factory-space-1.1.0.tgz", + "integrity": "sha512-cRzEj7c0OL4Mw2v6nwzttyOZe8XY/Z8G0rzmWQZTBi/jjwyw/U4uqKtUORXQrR5bAZZnbTI/feRV/R7hc4jQYQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-factory-title": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-title/-/micromark-factory-title-1.1.0.tgz", + "integrity": "sha512-J7n9R3vMmgjDOCY8NPw55jiyaQnH5kBdV2/UXCtZIpnHH3P6nHUKaH7XXEYuWwx/xUJcawa8plLBEjMPU24HzQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-factory-whitespace": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-factory-whitespace/-/micromark-factory-whitespace-1.1.0.tgz", + "integrity": "sha512-v2WlmiymVSp5oMg+1Q0N1Lxmt6pMhIHD457whWM7/GUlEks1hI9xj5w3zbc4uuMKXGisksZk8DzP2UyGbGqNsQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-factory-space": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-util-character": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/micromark-util-character/-/micromark-util-character-1.2.0.tgz", + "integrity": "sha512-lXraTwcX3yH/vMDaFWCQJP1uIszLVebzUa3ZHdrgxr7KEU/9mL4mVgCpGbyhvNLNlauROiNUq7WN5u7ndbY6xg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-util-chunked": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-chunked/-/micromark-util-chunked-1.1.0.tgz", + "integrity": "sha512-Ye01HXpkZPNcV6FiyoW2fGZDUw4Yc7vT0E9Sad83+bEDiCJ1uXu0S3mr8WLpsz3HaG3x2q0HM6CTuPdcZcluFQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/micromark-util-classify-character": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-classify-character/-/micromark-util-classify-character-1.1.0.tgz", + "integrity": "sha512-SL0wLxtKSnklKSUplok1WQFoGhUdWYKggKUiqhX+Swala+BtptGCu5iPRc+xvzJ4PXE/hwM3FNXsfEVgoZsWbw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-util-combine-extensions": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-combine-extensions/-/micromark-util-combine-extensions-1.1.0.tgz", + "integrity": "sha512-Q20sp4mfNf9yEqDL50WwuWZHUrCO4fEyeDCnMGmG5Pr0Cz15Uo7KBs6jq+dq0EgX4DPwwrh9m0X+zPV1ypFvUA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^1.0.0", + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-util-decode-numeric-character-reference": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-decode-numeric-character-reference/-/micromark-util-decode-numeric-character-reference-1.1.0.tgz", + "integrity": "sha512-m9V0ExGv0jB1OT21mrWcuf4QhP46pH1KkfWy9ZEezqHKAxkj4mPCy3nIH1rkbdMlChLHX531eOrymlwyZIf2iw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/micromark-util-decode-string": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-decode-string/-/micromark-util-decode-string-1.1.0.tgz", + "integrity": "sha512-YphLGCK8gM1tG1bd54azwyrQRjCFcmgj2S2GoJDNnh4vYtnL38JS8M4gpxzOPNyHdNEpheyWXCTnnTDY3N+NVQ==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "decode-named-character-reference": "^1.0.0", + "micromark-util-character": "^1.0.0", + "micromark-util-decode-numeric-character-reference": "^1.0.0", + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/micromark-util-encode": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-encode/-/micromark-util-encode-1.1.0.tgz", + "integrity": "sha512-EuEzTWSTAj9PA5GOAs992GzNh2dGQO52UvAbtSOMvXTxv3Criqb6IOzJUBCmEqrrXSblJIJBbFFv6zPxpreiJw==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-html-tag-name": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/micromark-util-html-tag-name/-/micromark-util-html-tag-name-1.2.0.tgz", + "integrity": "sha512-VTQzcuQgFUD7yYztuQFKXT49KghjtETQ+Wv/zUjGSGBioZnkA4P1XXZPT1FHeJA6RwRXSF47yvJ1tsJdoxwO+Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-normalize-identifier": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-normalize-identifier/-/micromark-util-normalize-identifier-1.1.0.tgz", + "integrity": "sha512-N+w5vhqrBihhjdpM8+5Xsxy71QWqGn7HYNUvch71iV2PM7+E3uWGox1Qp90loa1ephtCxG2ftRV/Conitc6P2Q==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/micromark-util-resolve-all": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-resolve-all/-/micromark-util-resolve-all-1.1.0.tgz", + "integrity": "sha512-b/G6BTMSg+bX+xVCshPTPyAu2tmA0E4X98NSR7eIbeC6ycCqCeE7wjfDIgzEbkzdEVJXRtOG4FbEm/uGbCRouA==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-types": "^1.0.0" + } + }, + "node_modules/micromark-util-sanitize-uri": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/micromark-util-sanitize-uri/-/micromark-util-sanitize-uri-1.2.0.tgz", + "integrity": "sha512-QO4GXv0XZfWey4pYFndLUKEAktKkG5kZTdUNaTAkzbuJxn2tNBOr+QtxR2XpWaMhbImT2dPzyLrPXLlPhph34A==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-character": "^1.0.0", + "micromark-util-encode": "^1.0.0", + "micromark-util-symbol": "^1.0.0" + } + }, + "node_modules/micromark-util-subtokenize": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-subtokenize/-/micromark-util-subtokenize-1.1.0.tgz", + "integrity": "sha512-kUQHyzRoxvZO2PuLzMt2P/dwVsTiivCK8icYTeR+3WgbuPqfHgPPy7nFKbeqRivBvn/3N3GBiNC+JRTMSxEC7A==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT", + "dependencies": { + "micromark-util-chunked": "^1.0.0", + "micromark-util-symbol": "^1.0.0", + "micromark-util-types": "^1.0.0", + "uvu": "^0.5.0" + } + }, + "node_modules/micromark-util-symbol": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-symbol/-/micromark-util-symbol-1.1.0.tgz", + "integrity": "sha512-uEjpEYY6KMs1g7QfJ2eX1SQEV+ZT4rUD3UcF6l57acZvLNK7PBZL+ty82Z1qhK1/yXIY4bdx04FKMgR0g4IAag==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/micromark-util-types": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/micromark-util-types/-/micromark-util-types-1.1.0.tgz", + "integrity": "sha512-ukRBgie8TIAcacscVHSiddHjO4k/q3pnedmzMQ4iwDcK0FtFCohKOlFbaOL/mPgfnPsL3C1ZyxJa4sbWrBl3jg==", + "dev": true, + "funding": [ + { + "type": "GitHub Sponsors", + "url": "https://github.com/sponsors/unifiedjs" + }, + { + "type": "OpenCollective", + "url": "https://opencollective.com/unified" + } + ], + "license": "MIT" + }, + "node_modules/minisearch": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/minisearch/-/minisearch-7.1.2.tgz", + "integrity": "sha512-R1Pd9eF+MD5JYDDSPAp/q1ougKglm14uEkPMvQ/05RGmx6G9wvmLTrTI/Q5iPNJLYqNdsDQ7qTGIcNWR+FrHmA==", + "dev": true, + "license": "MIT" + }, + "node_modules/mitt": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/mitt/-/mitt-3.0.1.tgz", + "integrity": "sha512-vKivATfr97l2/QBCYAkXYDbrIWPM2IIKEl7YPhjCvKlG3kE2gm+uBo6nEXK3M5/Ffh/FLpKExzOQ3JJoJGFKBw==", + "dev": true, + "license": "MIT" + }, + "node_modules/mri": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/mri/-/mri-1.2.0.tgz", + "integrity": "sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=4" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "dev": true, + "license": "MIT" + }, + "node_modules/nanoid": { + "version": "3.3.11", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz", + "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==", + "devOptional": true, + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "bin": { + "nanoid": "bin/nanoid.cjs" + }, + "engines": { + "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1" + } + }, + "node_modules/non-layered-tidy-tree-layout": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/non-layered-tidy-tree-layout/-/non-layered-tidy-tree-layout-2.0.2.tgz", + "integrity": "sha512-gkXMxRzUH+PB0ax9dUN0yYF0S25BqeAYqhgMaLUFmpXLEk7Fcu8f4emJuOAY0V8kjDICxROIKsTAKsV/v355xw==", + "dev": true, + "license": "MIT" + }, + "node_modules/oniguruma-to-es": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/oniguruma-to-es/-/oniguruma-to-es-3.1.1.tgz", + "integrity": "sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "emoji-regex-xs": "^1.0.0", + "regex": "^6.0.1", + "regex-recursion": "^6.0.2" + } + }, + "node_modules/perfect-debounce": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/perfect-debounce/-/perfect-debounce-1.0.0.tgz", + "integrity": "sha512-xCy9V055GLEqoFaHoC1SoLIaLmWctgCUaBaWxDZ7/Zx4CTyX7cJQLJOok/orfjZAh9kEYpjJa4d0KcJmCbctZA==", + "dev": true, + "license": "MIT" + }, + "node_modules/picocolors": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", + "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", + "devOptional": true, + "license": "ISC" + }, + "node_modules/postcss": { + "version": "8.5.6", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.6.tgz", + "integrity": "sha512-3Ybi1tAuwAP9s0r1UQ2J4n5Y0G05bJkpUIO0/bI9MhwmD70S5aTWbXGBwxHrelT+XM1k6dM0pk+SwNkpTRN7Pg==", + "devOptional": true, + "funding": [ + { + "type": "opencollective", + "url": "https://opencollective.com/postcss/" + }, + { + "type": "tidelift", + "url": "https://tidelift.com/funding/github/npm/postcss" + }, + { + "type": "github", + "url": "https://github.com/sponsors/ai" + } + ], + "license": "MIT", + "dependencies": { + "nanoid": "^3.3.11", + "picocolors": "^1.1.1", + "source-map-js": "^1.2.1" + }, + "engines": { + "node": "^10 || ^12 || >=14" + } + }, + "node_modules/preact": { + "version": "10.26.9", + "resolved": "https://registry.npmjs.org/preact/-/preact-10.26.9.tgz", + "integrity": "sha512-SSjF9vcnF27mJK1XyFMNJzFd5u3pQiATFqoaDy03XuN00u4ziveVVEGt5RKJrDR8MHE/wJo9Nnad56RLzS2RMA==", + "dev": true, + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/preact" + } + }, + "node_modules/property-information": { + "version": "7.1.0", + "resolved": "https://registry.npmjs.org/property-information/-/property-information-7.1.0.tgz", + "integrity": "sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/regex": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/regex/-/regex-6.0.1.tgz", + "integrity": "sha512-uorlqlzAKjKQZ5P+kTJr3eeJGSVroLKoHmquUj4zHWuR+hEyNqlXsSKlYYF5F4NI6nl7tWCs0apKJ0lmfsXAPA==", + "dev": true, + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-recursion": { + "version": "6.0.2", + "resolved": "https://registry.npmjs.org/regex-recursion/-/regex-recursion-6.0.2.tgz", + "integrity": "sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==", + "dev": true, + "license": "MIT", + "dependencies": { + "regex-utilities": "^2.3.0" + } + }, + "node_modules/regex-utilities": { + "version": "2.3.0", + "resolved": "https://registry.npmjs.org/regex-utilities/-/regex-utilities-2.3.0.tgz", + "integrity": "sha512-8VhliFJAWRaUiVvREIiW2NXXTmHs4vMNnSzuJVhscgmGav3g9VDxLrQndI3dZZVVdp0ZO/5v0xmX516/7M9cng==", + "dev": true, + "license": "MIT" + }, + "node_modules/rfdc": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz", + "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==", + "dev": true, + "license": "MIT" + }, + "node_modules/robust-predicates": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/robust-predicates/-/robust-predicates-3.0.2.tgz", + "integrity": "sha512-IXgzBWvWQwE6PrDI05OvmXUIruQTcoMDzRsOd5CDvHCVLcLHMTSYvOK5Cm46kWqlV3yAbuSpBZdJ5oP5OUoStg==", + "dev": true, + "license": "Unlicense" + }, + "node_modules/rollup": { + "version": "4.44.2", + "resolved": "https://registry.npmjs.org/rollup/-/rollup-4.44.2.tgz", + "integrity": "sha512-PVoapzTwSEcelaWGth3uR66u7ZRo6qhPHc0f2uRO9fX6XDVNrIiGYS0Pj9+R8yIIYSD/mCx2b16Ws9itljKSPg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/estree": "1.0.8" + }, + "bin": { + "rollup": "dist/bin/rollup" + }, + "engines": { + "node": ">=18.0.0", + "npm": ">=8.0.0" + }, + "optionalDependencies": { + "@rollup/rollup-android-arm-eabi": "4.44.2", + "@rollup/rollup-android-arm64": "4.44.2", + "@rollup/rollup-darwin-arm64": "4.44.2", + "@rollup/rollup-darwin-x64": "4.44.2", + "@rollup/rollup-freebsd-arm64": "4.44.2", + "@rollup/rollup-freebsd-x64": "4.44.2", + "@rollup/rollup-linux-arm-gnueabihf": "4.44.2", + "@rollup/rollup-linux-arm-musleabihf": "4.44.2", + "@rollup/rollup-linux-arm64-gnu": "4.44.2", + "@rollup/rollup-linux-arm64-musl": "4.44.2", + "@rollup/rollup-linux-loongarch64-gnu": "4.44.2", + "@rollup/rollup-linux-powerpc64le-gnu": "4.44.2", + "@rollup/rollup-linux-riscv64-gnu": "4.44.2", + "@rollup/rollup-linux-riscv64-musl": "4.44.2", + "@rollup/rollup-linux-s390x-gnu": "4.44.2", + "@rollup/rollup-linux-x64-gnu": "4.44.2", + "@rollup/rollup-linux-x64-musl": "4.44.2", + "@rollup/rollup-win32-arm64-msvc": "4.44.2", + "@rollup/rollup-win32-ia32-msvc": "4.44.2", + "@rollup/rollup-win32-x64-msvc": "4.44.2", + "fsevents": "~2.3.2" + } + }, + "node_modules/rw": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/rw/-/rw-1.3.3.tgz", + "integrity": "sha512-PdhdWy89SiZogBLaw42zdeqtRJ//zFd2PgQavcICDUgJT5oW10QCRKbJ6bg4r0/UY2M6BWd5tkxuGFRvCkgfHQ==", + "dev": true, + "license": "BSD-3-Clause" + }, + "node_modules/sade": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/sade/-/sade-1.8.1.tgz", + "integrity": "sha512-xal3CZX1Xlo/k4ApwCFrHVACi9fBqJ7V+mwhBsuf/1IOKbBy098Fex+Wa/5QMubw09pSZ/u8EY8PWgevJsXp1A==", + "dev": true, + "license": "MIT", + "dependencies": { + "mri": "^1.1.0" + }, + "engines": { + "node": ">=6" + } + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "dev": true, + "license": "MIT" + }, + "node_modules/sax": { + "version": "1.4.1", + "resolved": "https://registry.npmjs.org/sax/-/sax-1.4.1.tgz", + "integrity": "sha512-+aWOz7yVScEGoKNd4PA10LZ8sk0A/z5+nXQG5giUO5rprX9jgYsTdov9qCchZiPIZezbZH+jRut8nPodFAX4Jg==", + "license": "ISC" + }, + "node_modules/search-insights": { + "version": "2.17.3", + "resolved": "https://registry.npmjs.org/search-insights/-/search-insights-2.17.3.tgz", + "integrity": "sha512-RQPdCYTa8A68uM2jwxoY842xDhvx3E5LFL1LxvxCNMev4o5mLuokczhzjAgGwUZBAmOKZknArSxLKmXtIi2AxQ==", + "dev": true, + "license": "MIT", + "peer": true + }, + "node_modules/shiki": { + "version": "2.5.0", + "resolved": "https://registry.npmjs.org/shiki/-/shiki-2.5.0.tgz", + "integrity": "sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/core": "2.5.0", + "@shikijs/engine-javascript": "2.5.0", + "@shikijs/engine-oniguruma": "2.5.0", + "@shikijs/langs": "2.5.0", + "@shikijs/themes": "2.5.0", + "@shikijs/types": "2.5.0", + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/sitemap": { + "version": "7.1.2", + "resolved": "https://registry.npmjs.org/sitemap/-/sitemap-7.1.2.tgz", + "integrity": "sha512-ARCqzHJ0p4gWt+j7NlU5eDlIO9+Rkr/JhPFZKKQ1l5GCus7rJH4UdrlVAh0xC/gDS/Qir2UMxqYNHtsKr2rpCw==", + "license": "MIT", + "dependencies": { + "@types/node": "^17.0.5", + "@types/sax": "^1.2.1", + "arg": "^5.0.0", + "sax": "^1.2.4" + }, + "bin": { + "sitemap": "dist/cli.js" + }, + "engines": { + "node": ">=12.0.0", + "npm": ">=5.6.0" + } + }, + "node_modules/source-map": { + "version": "0.6.1", + "resolved": "https://registry.npmjs.org/source-map/-/source-map-0.6.1.tgz", + "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/source-map-js": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", + "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", + "devOptional": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/source-map-support": { + "version": "0.5.21", + "resolved": "https://registry.npmjs.org/source-map-support/-/source-map-support-0.5.21.tgz", + "integrity": "sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==", + "dev": true, + "license": "MIT", + "dependencies": { + "buffer-from": "^1.0.0", + "source-map": "^0.6.0" + } + }, + "node_modules/space-separated-tokens": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/space-separated-tokens/-/space-separated-tokens-2.0.2.tgz", + "integrity": "sha512-PEGlAwrG8yXGXRjW32fGbg66JAlOAwbObuqVoJpv/mRgoWDQfgH1wDPvtzWyUSNAXBGSk8h755YDbbcEy3SH2Q==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/speakingurl": { + "version": "14.0.1", + "resolved": "https://registry.npmjs.org/speakingurl/-/speakingurl-14.0.1.tgz", + "integrity": "sha512-1POYv7uv2gXoyGFpBCmpDVSNV74IfsWlDW216UPjbWufNf+bSU6GdbDsxdcxtfwb4xlI3yxzOTKClUosxARYrQ==", + "dev": true, + "license": "BSD-3-Clause", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/stringify-entities": { + "version": "4.0.4", + "resolved": "https://registry.npmjs.org/stringify-entities/-/stringify-entities-4.0.4.tgz", + "integrity": "sha512-IwfBptatlO+QCJUo19AqvrPNqlVMpW9YEL2LIVY+Rpv2qsjCGxaDLNRgeGsQWJhfItebuJhsGSLjaBbNSQ+ieg==", + "dev": true, + "license": "MIT", + "dependencies": { + "character-entities-html4": "^2.0.0", + "character-entities-legacy": "^3.0.0" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/stylis": { + "version": "4.3.6", + "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.3.6.tgz", + "integrity": "sha512-yQ3rwFWRfwNUY7H5vpU0wfdkNSnvnJinhF9830Swlaxl03zsOjCfmX0ugac+3LtK0lYSgwL/KXc8oYL3mG4YFQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/superjson": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/superjson/-/superjson-2.2.2.tgz", + "integrity": "sha512-5JRxVqC8I8NuOUjzBbvVJAKNM8qoVuH0O77h4WInc/qC2q5IreqKxYwgkga3PfA22OayK2ikceb/B26dztPl+Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "copy-anything": "^3.0.2" + }, + "engines": { + "node": ">=16" + } + }, + "node_modules/tabbable": { + "version": "6.2.0", + "resolved": "https://registry.npmjs.org/tabbable/-/tabbable-6.2.0.tgz", + "integrity": "sha512-Cat63mxsVJlzYvN51JmVXIgNoUokrIaT2zLclCXjRd8boZ0004U4KCs/sToJ75C6sdlByWxpYnb5Boif1VSFew==", + "dev": true, + "license": "MIT" + }, + "node_modules/terser": { + "version": "5.43.1", + "resolved": "https://registry.npmjs.org/terser/-/terser-5.43.1.tgz", + "integrity": "sha512-+6erLbBm0+LROX2sPXlUYx/ux5PyE9K/a92Wrt6oA+WDAoFTdpHE5tCYCI5PNzq2y8df4rA+QgHLJuR4jNymsg==", + "dev": true, + "license": "BSD-2-Clause", + "dependencies": { + "@jridgewell/source-map": "^0.3.3", + "acorn": "^8.14.0", + "commander": "^2.20.0", + "source-map-support": "~0.5.20" + }, + "bin": { + "terser": "bin/terser" + }, + "engines": { + "node": ">=10" + } + }, + "node_modules/terser/node_modules/commander": { + "version": "2.20.3", + "resolved": "https://registry.npmjs.org/commander/-/commander-2.20.3.tgz", + "integrity": "sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/trim-lines": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/trim-lines/-/trim-lines-3.0.1.tgz", + "integrity": "sha512-kRj8B+YHZCc9kQYdWfJB2/oUl9rA99qbowYYBtr4ui4mZyAQ2JpvVBd/6U2YloATfqBhBTSMhTpgBHtU0Mf3Rg==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + }, + "node_modules/ts-dedent": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/ts-dedent/-/ts-dedent-2.2.0.tgz", + "integrity": "sha512-q5W7tVM71e2xjHZTlgfTDoPF/SmqKG5hddq9SzR49CH2hayqRKJtQ4mtRlSxKaJlR/+9rEM+mnBHf7I2/BQcpQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6.10" + } + }, + "node_modules/undici-types": { + "version": "7.8.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.8.0.tgz", + "integrity": "sha512-9UJ2xGDvQ43tYyVMpuHlsgApydB8ZKfVYTsLDhXkFL/6gfkp+U8xTGdh8pMJv1SpZna0zxG1DwsKZsreLbXBxw==", + "dev": true, + "license": "MIT", + "optional": true, + "peer": true + }, + "node_modules/unist-util-is": { + "version": "6.0.0", + "resolved": "https://registry.npmjs.org/unist-util-is/-/unist-util-is-6.0.0.tgz", + "integrity": "sha512-2qCTHimwdxLfz+YzdGfkqNlH0tLi9xjTnHddPmJwtIG9MGsdbutfTc4P+haPD7l7Cjxf/WZj+we5qfVPvvxfYw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-is/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/unist-util-position": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-position/-/unist-util-position-5.0.0.tgz", + "integrity": "sha512-fucsC7HjXvkB5R3kTCO7kUjRdrS0BJt3M/FPxmHMBOm8JQi2BsHAHFsy27E0EolP8rp0NzXsJ+jNPyDWvOJZPA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-position/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/unist-util-stringify-position": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-3.0.3.tgz", + "integrity": "sha512-k5GzIBZ/QatR8N5X2y+drfpWG8IDBzdnVj6OInRNWm1oXrzydiaAT2OQiA8DPRRZyAKb9b6I2a6PxYklZD0gKg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^2.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/unist-util-visit/-/unist-util-visit-5.0.0.tgz", + "integrity": "sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0", + "unist-util-visit-parents": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents": { + "version": "6.0.1", + "resolved": "https://registry.npmjs.org/unist-util-visit-parents/-/unist-util-visit-parents-6.0.1.tgz", + "integrity": "sha512-L/PqWzfTP9lzzEa6CKs0k2nARxTdZduw3zyh8d2NVBnsyvHjSX4TWse388YrrQKbvI8w20fGjGlhgT96WwKykw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-is": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/unist-util-visit-parents/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/unist-util-visit/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/uuid": { + "version": "9.0.1", + "resolved": "https://registry.npmjs.org/uuid/-/uuid-9.0.1.tgz", + "integrity": "sha512-b+1eJOlsR9K8HJpow9Ok3fiWOWSIcIzXodvv0rQjVoOVNpWMpxf1wZNpt4y9h10odCNrqnYp1OBzRktckBe3sA==", + "dev": true, + "funding": [ + "https://github.com/sponsors/broofa", + "https://github.com/sponsors/ctavan" + ], + "license": "MIT", + "bin": { + "uuid": "dist/bin/uuid" + } + }, + "node_modules/uvu": { + "version": "0.5.6", + "resolved": "https://registry.npmjs.org/uvu/-/uvu-0.5.6.tgz", + "integrity": "sha512-+g8ENReyr8YsOc6fv/NVJs2vFdHBnBNdfE49rshrTzDWOlUx4Gq7KOS2GD8eqhy2j+Ejq29+SbKH8yjkAqXqoA==", + "dev": true, + "license": "MIT", + "dependencies": { + "dequal": "^2.0.0", + "diff": "^5.0.0", + "kleur": "^4.0.3", + "sade": "^1.7.3" + }, + "bin": { + "uvu": "bin.js" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/vfile": { + "version": "6.0.3", + "resolved": "https://registry.npmjs.org/vfile/-/vfile-6.0.3.tgz", + "integrity": "sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "vfile-message": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message": { + "version": "4.0.2", + "resolved": "https://registry.npmjs.org/vfile-message/-/vfile-message-4.0.2.tgz", + "integrity": "sha512-jRDZ1IMLttGj41KcZvlrYAaI3CfqpLpfpf+Mfig13viT6NKvRzWZ+lXz0Y5D60w6uJIBAOGq9mSHf0gktF0duw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0", + "unist-util-stringify-position": "^4.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile-message/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/vfile-message/node_modules/unist-util-stringify-position": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/unist-util-stringify-position/-/unist-util-stringify-position-4.0.0.tgz", + "integrity": "sha512-0ASV06AAoKCDkS2+xw5RXJywruurpbC4JZSm7nr7MOt1ojAzvyyaO+UxZf18j8FCF6kmzCZKcAgN/yu2gm2XgQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "^3.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + } + }, + "node_modules/vfile/node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/vitepress": { + "version": "1.6.3", + "resolved": "https://registry.npmjs.org/vitepress/-/vitepress-1.6.3.tgz", + "integrity": "sha512-fCkfdOk8yRZT8GD9BFqusW3+GggWYZ/rYncOfmgcDtP3ualNHCAg+Robxp2/6xfH1WwPHtGpPwv7mbA3qomtBw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@docsearch/css": "3.8.2", + "@docsearch/js": "3.8.2", + "@iconify-json/simple-icons": "^1.2.21", + "@shikijs/core": "^2.1.0", + "@shikijs/transformers": "^2.1.0", + "@shikijs/types": "^2.1.0", + "@types/markdown-it": "^14.1.2", + "@vitejs/plugin-vue": "^5.2.1", + "@vue/devtools-api": "^7.7.0", + "@vue/shared": "^3.5.13", + "@vueuse/core": "^12.4.0", + "@vueuse/integrations": "^12.4.0", + "focus-trap": "^7.6.4", + "mark.js": "8.11.1", + "minisearch": "^7.1.1", + "shiki": "^2.1.0", + "vite": "^5.4.14", + "vue": "^3.5.13" + }, + "bin": { + "vitepress": "bin/vitepress.js" + }, + "peerDependencies": { + "markdown-it-mathjax3": "^4", + "postcss": "^8" + }, + "peerDependenciesMeta": { + "markdown-it-mathjax3": { + "optional": true + }, + "postcss": { + "optional": true + } + } + }, + "node_modules/vitepress-plugin-mermaid": { + "version": "2.0.17", + "resolved": "https://registry.npmjs.org/vitepress-plugin-mermaid/-/vitepress-plugin-mermaid-2.0.17.tgz", + "integrity": "sha512-IUzYpwf61GC6k0XzfmAmNrLvMi9TRrVRMsUyCA8KNXhg/mQ1VqWnO0/tBVPiX5UoKF1mDUwqn5QV4qAJl6JnUg==", + "dev": true, + "license": "MIT", + "optionalDependencies": { + "@mermaid-js/mermaid-mindmap": "^9.3.0" + }, + "peerDependencies": { + "mermaid": "10 || 11", + "vitepress": "^1.0.0 || ^1.0.0-alpha" + } + }, + "node_modules/vitepress/node_modules/@types/node": { + "version": "24.0.13", + "resolved": "https://registry.npmjs.org/@types/node/-/node-24.0.13.tgz", + "integrity": "sha512-Qm9OYVOFHFYg3wJoTSrz80hoec5Lia/dPp84do3X7dZvLikQvM1YpmvTBEdIr/e+U8HTkFjLHLnl78K/qjf+jQ==", + "dev": true, + "license": "MIT", + "optional": true, + "peer": true, + "dependencies": { + "undici-types": "~7.8.0" + } + }, + "node_modules/vitepress/node_modules/@vitejs/plugin-vue": { + "version": "5.2.4", + "resolved": "https://registry.npmjs.org/@vitejs/plugin-vue/-/plugin-vue-5.2.4.tgz", + "integrity": "sha512-7Yx/SXSOcQq5HiiV3orevHUFn+pmMB4cgbEkDYgnkUWb0WfeQ/wa2yFv6D5ICiCQOVpjA7vYDXrC7AGO8yjDHA==", + "dev": true, + "license": "MIT", + "engines": { + "node": "^18.0.0 || >=20.0.0" + }, + "peerDependencies": { + "vite": "^5.0.0 || ^6.0.0", + "vue": "^3.2.25" + } + }, + "node_modules/vitepress/node_modules/vite": { + "version": "5.4.19", + "resolved": "https://registry.npmjs.org/vite/-/vite-5.4.19.tgz", + "integrity": "sha512-qO3aKv3HoQC8QKiNSTuUM1l9o/XX3+c+VTgLHbJWHZGeTPVAg2XwazI9UWzoxjIJCGCV2zU60uqMzjeLZuULqA==", + "dev": true, + "license": "MIT", + "dependencies": { + "esbuild": "^0.21.3", + "postcss": "^8.4.43", + "rollup": "^4.20.0" + }, + "bin": { + "vite": "bin/vite.js" + }, + "engines": { + "node": "^18.0.0 || >=20.0.0" + }, + "funding": { + "url": "https://github.com/vitejs/vite?sponsor=1" + }, + "optionalDependencies": { + "fsevents": "~2.3.3" + }, + "peerDependencies": { + "@types/node": "^18.0.0 || >=20.0.0", + "less": "*", + "lightningcss": "^1.21.0", + "sass": "*", + "sass-embedded": "*", + "stylus": "*", + "sugarss": "*", + "terser": "^5.4.0" + }, + "peerDependenciesMeta": { + "@types/node": { + "optional": true + }, + "less": { + "optional": true + }, + "lightningcss": { + "optional": true + }, + "sass": { + "optional": true + }, + "sass-embedded": { + "optional": true + }, + "stylus": { + "optional": true + }, + "sugarss": { + "optional": true + }, + "terser": { + "optional": true + } + } + }, + "node_modules/vue": { + "version": "3.5.17", + "resolved": "https://registry.npmjs.org/vue/-/vue-3.5.17.tgz", + "integrity": "sha512-LbHV3xPN9BeljML+Xctq4lbz2lVHCR6DtbpTf5XIO6gugpXUN49j2QQPcMj086r9+AkJ0FfUT8xjulKKBkkr9g==", + "devOptional": true, + "license": "MIT", + "dependencies": { + "@vue/compiler-dom": "3.5.17", + "@vue/compiler-sfc": "3.5.17", + "@vue/runtime-dom": "3.5.17", + "@vue/server-renderer": "3.5.17", + "@vue/shared": "3.5.17" + }, + "peerDependencies": { + "typescript": "*" + }, + "peerDependenciesMeta": { + "typescript": { + "optional": true + } + } + }, + "node_modules/web-worker": { + "version": "1.5.0", + "resolved": "https://registry.npmjs.org/web-worker/-/web-worker-1.5.0.tgz", + "integrity": "sha512-RiMReJrTAiA+mBjGONMnjVDP2u3p9R1vkcGz6gDIrOMT3oGuYwX2WRMYI9ipkphSuE5XKEhydbhNEJh4NY9mlw==", + "dev": true, + "license": "Apache-2.0" + }, + "node_modules/zwitch": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/zwitch/-/zwitch-2.0.4.tgz", + "integrity": "sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==", + "dev": true, + "license": "MIT", + "funding": { + "type": "github", + "url": "https://github.com/sponsors/wooorm" + } + } + } +} diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 000000000..8b91e6aa5 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,20 @@ +{ + "scripts": { + "dev": "vitepress dev", + "build": "vitepress build", + "preview": "vitepress preview" + }, + "devDependencies": { + "mermaid": "10.9.3", + "terser": "^5.14.2", + "vitepress": "1.6.3", + "vitepress-plugin-mermaid": "2.0.17" + }, + "dependencies": { + "@vercel/analytics": "^1.2.2", + "@vercel/speed-insights": "^1.0.10", + "lodash": "^4.17.21", + "medium-zoom": "^1.1.0", + "sitemap": "^7.1.1" + } +} diff --git a/docs/public/icon.png b/docs/public/icon.png new file mode 100644 index 000000000..8e68fffb9 Binary files /dev/null and b/docs/public/icon.png differ diff --git a/docs/public/images/developer/contribute/issuer.png b/docs/public/images/developer/contribute/issuer.png new file mode 100644 index 000000000..b275938a5 Binary files /dev/null and b/docs/public/images/developer/contribute/issuer.png differ diff --git a/docs/public/images/developer/contribute/smart-contract-tree.jpg b/docs/public/images/developer/contribute/smart-contract-tree.jpg new file mode 100644 index 000000000..331e775b1 Binary files /dev/null and b/docs/public/images/developer/contribute/smart-contract-tree.jpg differ diff --git a/docs/public/images/developer/contribute/smart-contract.jpg b/docs/public/images/developer/contribute/smart-contract.jpg new file mode 100644 index 000000000..34afca99c Binary files /dev/null and b/docs/public/images/developer/contribute/smart-contract.jpg differ diff --git a/docs/public/images/developer/contribute/vc-process.jpeg b/docs/public/images/developer/contribute/vc-process.jpeg new file mode 100644 index 000000000..875e1ba9a Binary files /dev/null and b/docs/public/images/developer/contribute/vc-process.jpeg differ diff --git a/docs/public/images/developer/contribute/verifier.png b/docs/public/images/developer/contribute/verifier.png new file mode 100644 index 000000000..3cdb35537 Binary files /dev/null and b/docs/public/images/developer/contribute/verifier.png differ diff --git a/docs/public/images/developer/develop/contribute/system-app/install/end.jpg b/docs/public/images/developer/develop/contribute/system-app/install/end.jpg new file mode 100644 index 000000000..2e76febc9 Binary files /dev/null and b/docs/public/images/developer/develop/contribute/system-app/install/end.jpg differ diff --git a/docs/public/images/developer/develop/contribute/system-app/install/install.jpg b/docs/public/images/developer/develop/contribute/system-app/install/install.jpg new file mode 100644 index 000000000..c06848b3a Binary files /dev/null and b/docs/public/images/developer/develop/contribute/system-app/install/install.jpg differ diff --git a/docs/public/images/developer/develop/contribute/system-app/install/install2.jpg b/docs/public/images/developer/develop/contribute/system-app/install/install2.jpg new file mode 100644 index 000000000..4aa9aff74 Binary files /dev/null and b/docs/public/images/developer/develop/contribute/system-app/install/install2.jpg differ diff --git a/docs/public/images/developer/develop/contribute/system-app/other/edit_yaml.jpg b/docs/public/images/developer/develop/contribute/system-app/other/edit_yaml.jpg new file mode 100644 index 000000000..5ee16fa87 Binary files /dev/null and b/docs/public/images/developer/develop/contribute/system-app/other/edit_yaml.jpg differ diff --git a/docs/public/images/developer/develop/contribute/system-app/other/provider_registry.jpg b/docs/public/images/developer/develop/contribute/system-app/other/provider_registry.jpg new file mode 100644 index 000000000..4249c6d9b Binary files /dev/null and b/docs/public/images/developer/develop/contribute/system-app/other/provider_registry.jpg differ diff --git a/docs/public/images/developer/develop/restore.jpg b/docs/public/images/developer/develop/restore.jpg new file mode 100644 index 000000000..954356a79 Binary files /dev/null and b/docs/public/images/developer/develop/restore.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/backend/debug.jpg b/docs/public/images/developer/develop/tutorial/backend/debug.jpg new file mode 100644 index 000000000..3b6b603f6 Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/backend/debug.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/backend/dev.jpg b/docs/public/images/developer/develop/tutorial/backend/dev.jpg new file mode 100644 index 000000000..153a3ab7e Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/backend/dev.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/add-file.jpg b/docs/public/images/developer/develop/tutorial/create/add-file.jpg new file mode 100644 index 000000000..4c00a0e4d Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/add-file.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/bind-2.jpg b/docs/public/images/developer/develop/tutorial/create/bind-2.jpg new file mode 100644 index 000000000..0a953085c Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/bind-2.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/bind.jpg b/docs/public/images/developer/develop/tutorial/create/bind.jpg new file mode 100644 index 000000000..2547a02fa Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/bind.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/create.jpg b/docs/public/images/developer/develop/tutorial/create/create.jpg new file mode 100644 index 000000000..da36d384e Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/create.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/home.jpg b/docs/public/images/developer/develop/tutorial/create/home.jpg new file mode 100644 index 000000000..8cbd581cc Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/home.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/installing.jpg b/docs/public/images/developer/develop/tutorial/create/installing.jpg new file mode 100644 index 000000000..2e804e99e Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/installing.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/olares-manifest.jpg b/docs/public/images/developer/develop/tutorial/create/olares-manifest.jpg new file mode 100644 index 000000000..85117cc8f Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/olares-manifest.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/create/success.jpg b/docs/public/images/developer/develop/tutorial/create/success.jpg new file mode 100644 index 000000000..7104ef32f Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/create/success.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/frontend/preview.jpg b/docs/public/images/developer/develop/tutorial/frontend/preview.jpg new file mode 100644 index 000000000..5844c438b Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/frontend/preview.jpg differ diff --git a/docs/public/images/developer/develop/tutorial/frontend/preview2.jpg b/docs/public/images/developer/develop/tutorial/frontend/preview2.jpg new file mode 100644 index 000000000..455ac8a2b Binary files /dev/null and b/docs/public/images/developer/develop/tutorial/frontend/preview2.jpg differ diff --git a/docs/public/images/developer/install/olares-install.png b/docs/public/images/developer/install/olares-install.png new file mode 100644 index 000000000..44a2c80a5 Binary files /dev/null and b/docs/public/images/developer/install/olares-install.png differ diff --git a/docs/public/images/developer/install/precheck.png b/docs/public/images/developer/install/precheck.png new file mode 100644 index 000000000..593eba881 Binary files /dev/null and b/docs/public/images/developer/install/precheck.png differ diff --git a/docs/public/images/developer/install/running-pods.png b/docs/public/images/developer/install/running-pods.png new file mode 100644 index 000000000..b5e88a7e6 Binary files /dev/null and b/docs/public/images/developer/install/running-pods.png differ diff --git a/docs/public/images/how-to/larepass/abnormal_status.jpg b/docs/public/images/how-to/larepass/abnormal_status.jpg new file mode 100644 index 000000000..2be2bc1d8 Binary files /dev/null and b/docs/public/images/how-to/larepass/abnormal_status.jpg differ diff --git a/docs/public/images/how-to/larepass/account.png b/docs/public/images/how-to/larepass/account.png new file mode 100644 index 000000000..76b3ba9d4 Binary files /dev/null and b/docs/public/images/how-to/larepass/account.png differ diff --git a/docs/public/images/how-to/larepass/autofill_android.jpg b/docs/public/images/how-to/larepass/autofill_android.jpg new file mode 100644 index 000000000..7f841e0f1 Binary files /dev/null and b/docs/public/images/how-to/larepass/autofill_android.jpg differ diff --git a/docs/public/images/how-to/larepass/autofill_ios.jpg b/docs/public/images/how-to/larepass/autofill_ios.jpg new file mode 100644 index 000000000..7f00e994e Binary files /dev/null and b/docs/public/images/how-to/larepass/autofill_ios.jpg differ diff --git a/docs/public/images/how-to/larepass/choose_olares_id_type.png b/docs/public/images/how-to/larepass/choose_olares_id_type.png new file mode 100644 index 000000000..60a15deaf Binary files /dev/null and b/docs/public/images/how-to/larepass/choose_olares_id_type.png differ diff --git a/docs/public/images/how-to/larepass/connection_status.jpg b/docs/public/images/how-to/larepass/connection_status.jpg new file mode 100644 index 000000000..a5e8bb004 Binary files /dev/null and b/docs/public/images/how-to/larepass/connection_status.jpg differ diff --git a/docs/public/images/how-to/larepass/create_an_account.png b/docs/public/images/how-to/larepass/create_an_account.png new file mode 100644 index 000000000..029e51c8c Binary files /dev/null and b/docs/public/images/how-to/larepass/create_an_account.png differ diff --git a/docs/public/images/how-to/larepass/individual_olares_id.png b/docs/public/images/how-to/larepass/individual_olares_id.png new file mode 100644 index 000000000..def75635a Binary files /dev/null and b/docs/public/images/how-to/larepass/individual_olares_id.png differ diff --git a/docs/public/images/how-to/larepass/individual_olares_id_fast.png b/docs/public/images/how-to/larepass/individual_olares_id_fast.png new file mode 100644 index 000000000..6d6614a32 Binary files /dev/null and b/docs/public/images/how-to/larepass/individual_olares_id_fast.png differ diff --git a/docs/public/images/how-to/larepass/individual_olares_id_vc.png b/docs/public/images/how-to/larepass/individual_olares_id_vc.png new file mode 100644 index 000000000..3a81684e3 Binary files /dev/null and b/docs/public/images/how-to/larepass/individual_olares_id_vc.png differ diff --git a/docs/public/images/how-to/larepass/mnemonic_phrase.png b/docs/public/images/how-to/larepass/mnemonic_phrase.png new file mode 100644 index 000000000..6a21cda58 Binary files /dev/null and b/docs/public/images/how-to/larepass/mnemonic_phrase.png differ diff --git a/docs/public/images/how-to/larepass/new_an_account.png b/docs/public/images/how-to/larepass/new_an_account.png new file mode 100644 index 000000000..6445ef426 Binary files /dev/null and b/docs/public/images/how-to/larepass/new_an_account.png differ diff --git a/docs/public/images/how-to/larepass/organization_olares_id.png b/docs/public/images/how-to/larepass/organization_olares_id.png new file mode 100644 index 000000000..577d5ee14 Binary files /dev/null and b/docs/public/images/how-to/larepass/organization_olares_id.png differ diff --git a/docs/public/images/how-to/larepass/resource.jpg b/docs/public/images/how-to/larepass/resource.jpg new file mode 100644 index 000000000..14da2d537 Binary files /dev/null and b/docs/public/images/how-to/larepass/resource.jpg differ diff --git a/docs/public/images/how-to/larepass/setup_local_password.png b/docs/public/images/how-to/larepass/setup_local_password.png new file mode 100644 index 000000000..bc6d11de6 Binary files /dev/null and b/docs/public/images/how-to/larepass/setup_local_password.png differ diff --git a/docs/public/images/how-to/larepass/sync.jpg b/docs/public/images/how-to/larepass/sync.jpg new file mode 100644 index 000000000..1035464c5 Binary files /dev/null and b/docs/public/images/how-to/larepass/sync.jpg differ diff --git a/docs/public/images/how-to/larepass/terminus_name_advanced.png b/docs/public/images/how-to/larepass/terminus_name_advanced.png new file mode 100644 index 000000000..14930312d Binary files /dev/null and b/docs/public/images/how-to/larepass/terminus_name_advanced.png differ diff --git a/docs/public/images/how-to/larepass/termipass.jpg b/docs/public/images/how-to/larepass/termipass.jpg new file mode 100644 index 000000000..da3075c67 Binary files /dev/null and b/docs/public/images/how-to/larepass/termipass.jpg differ diff --git a/docs/public/images/how-to/larepass/vpn.jpg b/docs/public/images/how-to/larepass/vpn.jpg new file mode 100644 index 000000000..2cd7ea5cb Binary files /dev/null and b/docs/public/images/how-to/larepass/vpn.jpg differ diff --git a/docs/public/images/how-to/olares/6-digit_one-time_password.jpg b/docs/public/images/how-to/olares/6-digit_one-time_password.jpg new file mode 100644 index 000000000..d5c28f98e Binary files /dev/null and b/docs/public/images/how-to/olares/6-digit_one-time_password.jpg differ diff --git a/docs/public/images/how-to/olares/activate_olares.jpg b/docs/public/images/how-to/olares/activate_olares.jpg new file mode 100644 index 000000000..b4f2e2f10 Binary files /dev/null and b/docs/public/images/how-to/olares/activate_olares.jpg differ diff --git a/docs/public/images/how-to/olares/active_session_of_the_vault.png b/docs/public/images/how-to/olares/active_session_of_the_vault.png new file mode 100644 index 000000000..b36e7a435 Binary files /dev/null and b/docs/public/images/how-to/olares/active_session_of_the_vault.png differ diff --git a/docs/public/images/how-to/olares/application.png b/docs/public/images/how-to/olares/application.png new file mode 100644 index 000000000..83c3a2279 Binary files /dev/null and b/docs/public/images/how-to/olares/application.png differ diff --git a/docs/public/images/how-to/olares/application_activated.png b/docs/public/images/how-to/olares/application_activated.png new file mode 100644 index 000000000..92bbb8a0a Binary files /dev/null and b/docs/public/images/how-to/olares/application_activated.png differ diff --git a/docs/public/images/how-to/olares/application_activation.png b/docs/public/images/how-to/olares/application_activation.png new file mode 100644 index 000000000..33de7129f Binary files /dev/null and b/docs/public/images/how-to/olares/application_activation.png differ diff --git a/docs/public/images/how-to/olares/application_activation_third_party_domain.png b/docs/public/images/how-to/olares/application_activation_third_party_domain.png new file mode 100644 index 000000000..24ce17457 Binary files /dev/null and b/docs/public/images/how-to/olares/application_activation_third_party_domain.png differ diff --git a/docs/public/images/how-to/olares/application_add_sub_policies.png b/docs/public/images/how-to/olares/application_add_sub_policies.png new file mode 100644 index 000000000..5d3ce098f Binary files /dev/null and b/docs/public/images/how-to/olares/application_add_sub_policies.png differ diff --git a/docs/public/images/how-to/olares/application_details.png b/docs/public/images/how-to/olares/application_details.png new file mode 100644 index 000000000..9327aeb70 Binary files /dev/null and b/docs/public/images/how-to/olares/application_details.png differ diff --git a/docs/public/images/how-to/olares/application_domain_setup.png b/docs/public/images/how-to/olares/application_domain_setup.png new file mode 100644 index 000000000..70215cc54 Binary files /dev/null and b/docs/public/images/how-to/olares/application_domain_setup.png differ diff --git a/docs/public/images/how-to/olares/application_entrance.png b/docs/public/images/how-to/olares/application_entrance.png new file mode 100644 index 000000000..e871c324b Binary files /dev/null and b/docs/public/images/how-to/olares/application_entrance.png differ diff --git a/docs/public/images/how-to/olares/application_third_level_domain.png b/docs/public/images/how-to/olares/application_third_level_domain.png new file mode 100644 index 000000000..a594be73c Binary files /dev/null and b/docs/public/images/how-to/olares/application_third_level_domain.png differ diff --git a/docs/public/images/how-to/olares/application_third_party_domain.png b/docs/public/images/how-to/olares/application_third_party_domain.png new file mode 100644 index 000000000..ff501ed95 Binary files /dev/null and b/docs/public/images/how-to/olares/application_third_party_domain.png differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/01.jpg b/docs/public/images/how-to/olares/controlhub/browse/01.jpg new file mode 100644 index 000000000..42e01a6f4 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/01.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/02.jpg b/docs/public/images/how-to/olares/controlhub/browse/02.jpg new file mode 100644 index 000000000..4b8372c29 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/02.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/03.jpg b/docs/public/images/how-to/olares/controlhub/browse/03.jpg new file mode 100644 index 000000000..041924c83 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/03.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/04.jpg b/docs/public/images/how-to/olares/controlhub/browse/04.jpg new file mode 100644 index 000000000..ad243b4f1 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/04.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/05.jpg b/docs/public/images/how-to/olares/controlhub/browse/05.jpg new file mode 100644 index 000000000..1e9a29855 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/05.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/06-1.jpg b/docs/public/images/how-to/olares/controlhub/browse/06-1.jpg new file mode 100644 index 000000000..fafcb46e4 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/06-1.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/06-2.jpg b/docs/public/images/how-to/olares/controlhub/browse/06-2.jpg new file mode 100644 index 000000000..c5c5182cd Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/06-2.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/06.jpg b/docs/public/images/how-to/olares/controlhub/browse/06.jpg new file mode 100644 index 000000000..216ac463e Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/06.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/07.jpg b/docs/public/images/how-to/olares/controlhub/browse/07.jpg new file mode 100644 index 000000000..17ee0e7ec Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/07.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/08.jpg b/docs/public/images/how-to/olares/controlhub/browse/08.jpg new file mode 100644 index 000000000..f6ad34774 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/08.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/09.jpg b/docs/public/images/how-to/olares/controlhub/browse/09.jpg new file mode 100644 index 000000000..29a1c7c4d Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/09.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/10.jpg b/docs/public/images/how-to/olares/controlhub/browse/10.jpg new file mode 100644 index 000000000..db7f4481a Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/10.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/11.jpg b/docs/public/images/how-to/olares/controlhub/browse/11.jpg new file mode 100644 index 000000000..b60fe88df Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/11.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/12.jpg b/docs/public/images/how-to/olares/controlhub/browse/12.jpg new file mode 100644 index 000000000..10169e258 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/12.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/13.jpg b/docs/public/images/how-to/olares/controlhub/browse/13.jpg new file mode 100644 index 000000000..2b0212f16 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/13.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/14.jpg b/docs/public/images/how-to/olares/controlhub/browse/14.jpg new file mode 100644 index 000000000..8c8d039e7 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/14.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/browse/15.jpg b/docs/public/images/how-to/olares/controlhub/browse/15.jpg new file mode 100644 index 000000000..230bf349c Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/browse/15.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/01.jpg b/docs/public/images/how-to/olares/controlhub/middleware/01.jpg new file mode 100644 index 000000000..4e0ff39dc Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/01.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/02.jpg b/docs/public/images/how-to/olares/controlhub/middleware/02.jpg new file mode 100644 index 000000000..e9234821f Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/02.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/03.jpg b/docs/public/images/how-to/olares/controlhub/middleware/03.jpg new file mode 100644 index 000000000..e1f689c46 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/03.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/04.jpg b/docs/public/images/how-to/olares/controlhub/middleware/04.jpg new file mode 100644 index 000000000..9db812c47 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/04.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/05.jpg b/docs/public/images/how-to/olares/controlhub/middleware/05.jpg new file mode 100644 index 000000000..387aab7d3 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/05.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/06.jpg b/docs/public/images/how-to/olares/controlhub/middleware/06.jpg new file mode 100644 index 000000000..a0975cf8e Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/06.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/07.jpg b/docs/public/images/how-to/olares/controlhub/middleware/07.jpg new file mode 100644 index 000000000..4d77946dd Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/07.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/08.jpg b/docs/public/images/how-to/olares/controlhub/middleware/08.jpg new file mode 100644 index 000000000..652f9891c Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/08.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/09.jpg b/docs/public/images/how-to/olares/controlhub/middleware/09.jpg new file mode 100644 index 000000000..cc8b7d122 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/09.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/10.jpg b/docs/public/images/how-to/olares/controlhub/middleware/10.jpg new file mode 100644 index 000000000..7346a0faf Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/10.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/11.jpg b/docs/public/images/how-to/olares/controlhub/middleware/11.jpg new file mode 100644 index 000000000..b607095fd Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/11.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/12.jpg b/docs/public/images/how-to/olares/controlhub/middleware/12.jpg new file mode 100644 index 000000000..eb2c31d41 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/12.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/middleware/13.jpg b/docs/public/images/how-to/olares/controlhub/middleware/13.jpg new file mode 100644 index 000000000..e8c6b8027 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/middleware/13.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/namespace/01.jpg b/docs/public/images/how-to/olares/controlhub/namespace/01.jpg new file mode 100644 index 000000000..3932b9ff6 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/namespace/01.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/namespace/02.jpg b/docs/public/images/how-to/olares/controlhub/namespace/02.jpg new file mode 100644 index 000000000..2d14091ef Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/namespace/02.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/namespace/03.jpg b/docs/public/images/how-to/olares/controlhub/namespace/03.jpg new file mode 100644 index 000000000..3cf3e9a25 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/namespace/03.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/namespace/04.jpg b/docs/public/images/how-to/olares/controlhub/namespace/04.jpg new file mode 100644 index 000000000..cd4e23c45 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/namespace/04.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/pods/01.jpg b/docs/public/images/how-to/olares/controlhub/pods/01.jpg new file mode 100644 index 000000000..9466ae6f4 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/pods/01.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/pods/02.jpg b/docs/public/images/how-to/olares/controlhub/pods/02.jpg new file mode 100644 index 000000000..a4dbc6252 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/pods/02.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/pods/03.jpg b/docs/public/images/how-to/olares/controlhub/pods/03.jpg new file mode 100644 index 000000000..9b3302290 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/pods/03.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/pods/04.jpg b/docs/public/images/how-to/olares/controlhub/pods/04.jpg new file mode 100644 index 000000000..794f22d84 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/pods/04.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/resources/01.jpg b/docs/public/images/how-to/olares/controlhub/resources/01.jpg new file mode 100644 index 000000000..283afe602 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/resources/01.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/resources/02.jpg b/docs/public/images/how-to/olares/controlhub/resources/02.jpg new file mode 100644 index 000000000..8fba47048 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/resources/02.jpg differ diff --git a/docs/public/images/how-to/olares/controlhub/resources/03.jpg b/docs/public/images/how-to/olares/controlhub/resources/03.jpg new file mode 100644 index 000000000..ca8e5c642 Binary files /dev/null and b/docs/public/images/how-to/olares/controlhub/resources/03.jpg differ diff --git a/docs/public/images/how-to/olares/create_a_backup.png b/docs/public/images/how-to/olares/create_a_backup.png new file mode 100644 index 000000000..337177974 Binary files /dev/null and b/docs/public/images/how-to/olares/create_a_backup.png differ diff --git a/docs/public/images/how-to/olares/dashboard/analytics-2.jpg b/docs/public/images/how-to/olares/dashboard/analytics-2.jpg new file mode 100644 index 000000000..593bfb486 Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/analytics-2.jpg differ diff --git a/docs/public/images/how-to/olares/dashboard/analytics-3.jpg b/docs/public/images/how-to/olares/dashboard/analytics-3.jpg new file mode 100644 index 000000000..04ba01ac3 Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/analytics-3.jpg differ diff --git a/docs/public/images/how-to/olares/dashboard/analytics.jpg b/docs/public/images/how-to/olares/dashboard/analytics.jpg new file mode 100644 index 000000000..04f57d8b7 Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/analytics.jpg differ diff --git a/docs/public/images/how-to/olares/dashboard/applications.jpg b/docs/public/images/how-to/olares/dashboard/applications.jpg new file mode 100644 index 000000000..84c83406a Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/applications.jpg differ diff --git a/docs/public/images/how-to/olares/dashboard/overview.jpg b/docs/public/images/how-to/olares/dashboard/overview.jpg new file mode 100644 index 000000000..bca14e65f Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/overview.jpg differ diff --git a/docs/public/images/how-to/olares/dashboard/resource-detail.jpg b/docs/public/images/how-to/olares/dashboard/resource-detail.jpg new file mode 100644 index 000000000..c36ec6757 Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/resource-detail.jpg differ diff --git a/docs/public/images/how-to/olares/dashboard/usage-ranking.jpg b/docs/public/images/how-to/olares/dashboard/usage-ranking.jpg new file mode 100644 index 000000000..a186575f7 Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/usage-ranking.jpg differ diff --git a/docs/public/images/how-to/olares/dashboard/user-usage.jpg b/docs/public/images/how-to/olares/dashboard/user-usage.jpg new file mode 100644 index 000000000..19fda2202 Binary files /dev/null and b/docs/public/images/how-to/olares/dashboard/user-usage.jpg differ diff --git a/docs/public/images/how-to/olares/desktop.jpg b/docs/public/images/how-to/olares/desktop.jpg new file mode 100644 index 000000000..07d4ba2d0 Binary files /dev/null and b/docs/public/images/how-to/olares/desktop.jpg differ diff --git a/docs/public/images/how-to/olares/desktop_application.jpg b/docs/public/images/how-to/olares/desktop_application.jpg new file mode 100644 index 000000000..bac08ea3e Binary files /dev/null and b/docs/public/images/how-to/olares/desktop_application.jpg differ diff --git a/docs/public/images/how-to/olares/desktop_application2.jpg b/docs/public/images/how-to/olares/desktop_application2.jpg new file mode 100644 index 000000000..37b42b84c Binary files /dev/null and b/docs/public/images/how-to/olares/desktop_application2.jpg differ diff --git a/docs/public/images/how-to/olares/desktop_lauchpad.jpg b/docs/public/images/how-to/olares/desktop_lauchpad.jpg new file mode 100644 index 000000000..f54f569be Binary files /dev/null and b/docs/public/images/how-to/olares/desktop_lauchpad.jpg differ diff --git a/docs/public/images/how-to/olares/desktop_search.jpg b/docs/public/images/how-to/olares/desktop_search.jpg new file mode 100644 index 000000000..1fa717860 Binary files /dev/null and b/docs/public/images/how-to/olares/desktop_search.jpg differ diff --git a/docs/public/images/how-to/olares/desktop_window.jpg b/docs/public/images/how-to/olares/desktop_window.jpg new file mode 100644 index 000000000..34f694919 Binary files /dev/null and b/docs/public/images/how-to/olares/desktop_window.jpg differ diff --git a/docs/public/images/how-to/olares/dify/01.jpg b/docs/public/images/how-to/olares/dify/01.jpg new file mode 100644 index 000000000..2ab265c3c Binary files /dev/null and b/docs/public/images/how-to/olares/dify/01.jpg differ diff --git a/docs/public/images/how-to/olares/dify/02.jpg b/docs/public/images/how-to/olares/dify/02.jpg new file mode 100644 index 000000000..6f4f6aafc Binary files /dev/null and b/docs/public/images/how-to/olares/dify/02.jpg differ diff --git a/docs/public/images/how-to/olares/dify/03.jpg b/docs/public/images/how-to/olares/dify/03.jpg new file mode 100644 index 000000000..bd7d89d19 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/03.jpg differ diff --git a/docs/public/images/how-to/olares/dify/04.jpg b/docs/public/images/how-to/olares/dify/04.jpg new file mode 100644 index 000000000..439447aa6 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/04.jpg differ diff --git a/docs/public/images/how-to/olares/dify/05.jpg b/docs/public/images/how-to/olares/dify/05.jpg new file mode 100644 index 000000000..3f5f6943d Binary files /dev/null and b/docs/public/images/how-to/olares/dify/05.jpg differ diff --git a/docs/public/images/how-to/olares/dify/06.jpg b/docs/public/images/how-to/olares/dify/06.jpg new file mode 100644 index 000000000..20ccb0d12 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/06.jpg differ diff --git a/docs/public/images/how-to/olares/dify/07.jpg b/docs/public/images/how-to/olares/dify/07.jpg new file mode 100644 index 000000000..c5b21eba0 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/07.jpg differ diff --git a/docs/public/images/how-to/olares/dify/08.jpg b/docs/public/images/how-to/olares/dify/08.jpg new file mode 100644 index 000000000..5afd96ea8 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/08.jpg differ diff --git a/docs/public/images/how-to/olares/dify/09.jpg b/docs/public/images/how-to/olares/dify/09.jpg new file mode 100644 index 000000000..7df272924 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/09.jpg differ diff --git a/docs/public/images/how-to/olares/dify/10.jpg b/docs/public/images/how-to/olares/dify/10.jpg new file mode 100644 index 000000000..e04847061 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/10.jpg differ diff --git a/docs/public/images/how-to/olares/dify/11.jpg b/docs/public/images/how-to/olares/dify/11.jpg new file mode 100644 index 000000000..e04847061 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/11.jpg differ diff --git a/docs/public/images/how-to/olares/dify/12.jpg b/docs/public/images/how-to/olares/dify/12.jpg new file mode 100644 index 000000000..4a10ac8a9 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/12.jpg differ diff --git a/docs/public/images/how-to/olares/dify/13.jpg b/docs/public/images/how-to/olares/dify/13.jpg new file mode 100644 index 000000000..1e726c5cc Binary files /dev/null and b/docs/public/images/how-to/olares/dify/13.jpg differ diff --git a/docs/public/images/how-to/olares/dify/14.jpg b/docs/public/images/how-to/olares/dify/14.jpg new file mode 100644 index 000000000..88405a7ee Binary files /dev/null and b/docs/public/images/how-to/olares/dify/14.jpg differ diff --git a/docs/public/images/how-to/olares/dify/15.jpg b/docs/public/images/how-to/olares/dify/15.jpg new file mode 100644 index 000000000..c07655547 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/15.jpg differ diff --git a/docs/public/images/how-to/olares/dify/16.jpg b/docs/public/images/how-to/olares/dify/16.jpg new file mode 100644 index 000000000..eec04be96 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/16.jpg differ diff --git a/docs/public/images/how-to/olares/dify/17.jpg b/docs/public/images/how-to/olares/dify/17.jpg new file mode 100644 index 000000000..0992f0cfe Binary files /dev/null and b/docs/public/images/how-to/olares/dify/17.jpg differ diff --git a/docs/public/images/how-to/olares/dify/18.jpg b/docs/public/images/how-to/olares/dify/18.jpg new file mode 100644 index 000000000..06ef11ac6 Binary files /dev/null and b/docs/public/images/how-to/olares/dify/18.jpg differ diff --git a/docs/public/images/how-to/olares/dns_resolution.png b/docs/public/images/how-to/olares/dns_resolution.png new file mode 100644 index 000000000..1e1ca8591 Binary files /dev/null and b/docs/public/images/how-to/olares/dns_resolution.png differ diff --git a/docs/public/images/how-to/olares/drive.jpg b/docs/public/images/how-to/olares/drive.jpg new file mode 100644 index 000000000..24a84b1d5 Binary files /dev/null and b/docs/public/images/how-to/olares/drive.jpg differ diff --git a/docs/public/images/how-to/olares/drive_right_click_menu.jpg b/docs/public/images/how-to/olares/drive_right_click_menu.jpg new file mode 100644 index 000000000..e820c85cf Binary files /dev/null and b/docs/public/images/how-to/olares/drive_right_click_menu.jpg differ diff --git a/docs/public/images/how-to/olares/drive_upload.jpg b/docs/public/images/how-to/olares/drive_upload.jpg new file mode 100644 index 000000000..65da3b5d7 Binary files /dev/null and b/docs/public/images/how-to/olares/drive_upload.jpg differ diff --git a/docs/public/images/how-to/olares/drive_view_mode.jpg b/docs/public/images/how-to/olares/drive_view_mode.jpg new file mode 100644 index 000000000..8552fdf03 Binary files /dev/null and b/docs/public/images/how-to/olares/drive_view_mode.jpg differ diff --git a/docs/public/images/how-to/olares/enter_olares_id.png b/docs/public/images/how-to/olares/enter_olares_id.png new file mode 100644 index 000000000..4b1f55baf Binary files /dev/null and b/docs/public/images/how-to/olares/enter_olares_id.png differ diff --git a/docs/public/images/how-to/olares/enter_password.jpg b/docs/public/images/how-to/olares/enter_password.jpg new file mode 100644 index 000000000..834fc8357 Binary files /dev/null and b/docs/public/images/how-to/olares/enter_password.jpg differ diff --git a/docs/public/images/how-to/olares/enter_password.png b/docs/public/images/how-to/olares/enter_password.png new file mode 100644 index 000000000..ae9f8d47d Binary files /dev/null and b/docs/public/images/how-to/olares/enter_password.png differ diff --git a/docs/public/images/how-to/olares/files.jpg b/docs/public/images/how-to/olares/files.jpg new file mode 100644 index 000000000..f2064aab0 Binary files /dev/null and b/docs/public/images/how-to/olares/files.jpg differ diff --git a/docs/public/images/how-to/olares/headScale_connection_status.png b/docs/public/images/how-to/olares/headScale_connection_status.png new file mode 100644 index 000000000..f537af81d Binary files /dev/null and b/docs/public/images/how-to/olares/headScale_connection_status.png differ diff --git a/docs/public/images/how-to/olares/home01.png b/docs/public/images/how-to/olares/home01.png new file mode 100644 index 000000000..dab44fb6c Binary files /dev/null and b/docs/public/images/how-to/olares/home01.png differ diff --git a/docs/public/images/how-to/olares/home02.png b/docs/public/images/how-to/olares/home02.png new file mode 100644 index 000000000..dc6626dd3 Binary files /dev/null and b/docs/public/images/how-to/olares/home02.png differ diff --git a/docs/public/images/how-to/olares/initialize_olares.png b/docs/public/images/how-to/olares/initialize_olares.png new file mode 100644 index 000000000..e00d5ec44 Binary files /dev/null and b/docs/public/images/how-to/olares/initialize_olares.png differ diff --git a/docs/public/images/how-to/olares/integration.png b/docs/public/images/how-to/olares/integration.png new file mode 100644 index 000000000..a8471d9d2 Binary files /dev/null and b/docs/public/images/how-to/olares/integration.png differ diff --git a/docs/public/images/how-to/olares/knowledge_base.png b/docs/public/images/how-to/olares/knowledge_base.png new file mode 100644 index 000000000..7804ff847 Binary files /dev/null and b/docs/public/images/how-to/olares/knowledge_base.png differ diff --git a/docs/public/images/how-to/olares/knowledge_create_new.png b/docs/public/images/how-to/olares/knowledge_create_new.png new file mode 100644 index 000000000..fed7f7024 Binary files /dev/null and b/docs/public/images/how-to/olares/knowledge_create_new.png differ diff --git a/docs/public/images/how-to/olares/list_of_sso_authorization_tokens.png b/docs/public/images/how-to/olares/list_of_sso_authorization_tokens.png new file mode 100644 index 000000000..ad310dcc7 Binary files /dev/null and b/docs/public/images/how-to/olares/list_of_sso_authorization_tokens.png differ diff --git a/docs/public/images/how-to/olares/login_history.png b/docs/public/images/how-to/olares/login_history.png new file mode 100644 index 000000000..5806f75af Binary files /dev/null and b/docs/public/images/how-to/olares/login_history.png differ diff --git a/docs/public/images/how-to/olares/login_olares_space.png b/docs/public/images/how-to/olares/login_olares_space.png new file mode 100644 index 000000000..7b0612eb3 Binary files /dev/null and b/docs/public/images/how-to/olares/login_olares_space.png differ diff --git a/docs/public/images/how-to/olares/market/application-details-2.jpg b/docs/public/images/how-to/olares/market/application-details-2.jpg new file mode 100644 index 000000000..b98067ed4 Binary files /dev/null and b/docs/public/images/how-to/olares/market/application-details-2.jpg differ diff --git a/docs/public/images/how-to/olares/market/application-details.jpg b/docs/public/images/how-to/olares/market/application-details.jpg new file mode 100644 index 000000000..723490d77 Binary files /dev/null and b/docs/public/images/how-to/olares/market/application-details.jpg differ diff --git a/docs/public/images/how-to/olares/market/discover.jpg b/docs/public/images/how-to/olares/market/discover.jpg new file mode 100644 index 000000000..cc34373a3 Binary files /dev/null and b/docs/public/images/how-to/olares/market/discover.jpg differ diff --git a/docs/public/images/how-to/olares/market/logs.jpg b/docs/public/images/how-to/olares/market/logs.jpg new file mode 100644 index 000000000..5badc1e54 Binary files /dev/null and b/docs/public/images/how-to/olares/market/logs.jpg differ diff --git a/docs/public/images/how-to/olares/market/myolares.jpg b/docs/public/images/how-to/olares/market/myolares.jpg new file mode 100644 index 000000000..1bd68c347 Binary files /dev/null and b/docs/public/images/how-to/olares/market/myolares.jpg differ diff --git a/docs/public/images/how-to/olares/market/update.jpg b/docs/public/images/how-to/olares/market/update.jpg new file mode 100644 index 000000000..610fbf55c Binary files /dev/null and b/docs/public/images/how-to/olares/market/update.jpg differ diff --git a/docs/public/images/how-to/olares/market/upload-custom-chart.jpg b/docs/public/images/how-to/olares/market/upload-custom-chart.jpg new file mode 100644 index 000000000..70a434c02 Binary files /dev/null and b/docs/public/images/how-to/olares/market/upload-custom-chart.jpg differ diff --git a/docs/public/images/how-to/olares/network_authority_policy.png b/docs/public/images/how-to/olares/network_authority_policy.png new file mode 100644 index 000000000..65025a29f Binary files /dev/null and b/docs/public/images/how-to/olares/network_authority_policy.png differ diff --git a/docs/public/images/how-to/olares/network_configuration.png b/docs/public/images/how-to/olares/network_configuration.png new file mode 100644 index 000000000..b1e1cfe2a Binary files /dev/null and b/docs/public/images/how-to/olares/network_configuration.png differ diff --git a/docs/public/images/how-to/olares/nft_bind_nft_images.png b/docs/public/images/how-to/olares/nft_bind_nft_images.png new file mode 100644 index 000000000..37ea28def Binary files /dev/null and b/docs/public/images/how-to/olares/nft_bind_nft_images.png differ diff --git a/docs/public/images/how-to/olares/nft_bound.png b/docs/public/images/how-to/olares/nft_bound.png new file mode 100644 index 000000000..ebeff2623 Binary files /dev/null and b/docs/public/images/how-to/olares/nft_bound.png differ diff --git a/docs/public/images/how-to/olares/nft_images.png b/docs/public/images/how-to/olares/nft_images.png new file mode 100644 index 000000000..aa571577f Binary files /dev/null and b/docs/public/images/how-to/olares/nft_images.png differ diff --git a/docs/public/images/how-to/olares/nft_import.png b/docs/public/images/how-to/olares/nft_import.png new file mode 100644 index 000000000..92ce9e63e Binary files /dev/null and b/docs/public/images/how-to/olares/nft_import.png differ diff --git a/docs/public/images/how-to/olares/olares.jpg b/docs/public/images/how-to/olares/olares.jpg new file mode 100644 index 000000000..fd66747ae Binary files /dev/null and b/docs/public/images/how-to/olares/olares.jpg differ diff --git a/docs/public/images/how-to/olares/one_time_password.png b/docs/public/images/how-to/olares/one_time_password.png new file mode 100644 index 000000000..917a4df3b Binary files /dev/null and b/docs/public/images/how-to/olares/one_time_password.png differ diff --git a/docs/public/images/how-to/olares/open_wizard_in_browser.jpg b/docs/public/images/how-to/olares/open_wizard_in_browser.jpg new file mode 100644 index 000000000..a049a7fcb Binary files /dev/null and b/docs/public/images/how-to/olares/open_wizard_in_browser.jpg differ diff --git a/docs/public/images/how-to/olares/profile.jpg b/docs/public/images/how-to/olares/profile.jpg new file mode 100644 index 000000000..7ebbf90f8 Binary files /dev/null and b/docs/public/images/how-to/olares/profile.jpg differ diff --git a/docs/public/images/how-to/olares/profile_avatar_setting.jpg b/docs/public/images/how-to/olares/profile_avatar_setting.jpg new file mode 100644 index 000000000..7e4ca9c5b Binary files /dev/null and b/docs/public/images/how-to/olares/profile_avatar_setting.jpg differ diff --git a/docs/public/images/how-to/olares/profile_backdrop.jpg b/docs/public/images/how-to/olares/profile_backdrop.jpg new file mode 100644 index 000000000..9af54feea Binary files /dev/null and b/docs/public/images/how-to/olares/profile_backdrop.jpg differ diff --git a/docs/public/images/how-to/olares/profile_blocks.jpg b/docs/public/images/how-to/olares/profile_blocks.jpg new file mode 100644 index 000000000..4ab626a8b Binary files /dev/null and b/docs/public/images/how-to/olares/profile_blocks.jpg differ diff --git a/docs/public/images/how-to/olares/profile_preview.jpg b/docs/public/images/how-to/olares/profile_preview.jpg new file mode 100644 index 000000000..ece71d2b5 Binary files /dev/null and b/docs/public/images/how-to/olares/profile_preview.jpg differ diff --git a/docs/public/images/how-to/olares/profile_share.jpg b/docs/public/images/how-to/olares/profile_share.jpg new file mode 100644 index 000000000..0f27aaf30 Binary files /dev/null and b/docs/public/images/how-to/olares/profile_share.jpg differ diff --git a/docs/public/images/how-to/olares/profile_social.jpg b/docs/public/images/how-to/olares/profile_social.jpg new file mode 100644 index 000000000..609f5d592 Binary files /dev/null and b/docs/public/images/how-to/olares/profile_social.jpg differ diff --git a/docs/public/images/how-to/olares/reset_password.png b/docs/public/images/how-to/olares/reset_password.png new file mode 100644 index 000000000..5ea42f581 Binary files /dev/null and b/docs/public/images/how-to/olares/reset_password.png differ diff --git a/docs/public/images/how-to/olares/second_confirmation.jpg b/docs/public/images/how-to/olares/second_confirmation.jpg new file mode 100644 index 000000000..1f0dbd772 Binary files /dev/null and b/docs/public/images/how-to/olares/second_confirmation.jpg differ diff --git a/docs/public/images/how-to/olares/select_a_reverse_proxy.jpeg b/docs/public/images/how-to/olares/select_a_reverse_proxy.jpeg new file mode 100644 index 000000000..8772103c0 Binary files /dev/null and b/docs/public/images/how-to/olares/select_a_reverse_proxy.jpeg differ diff --git a/docs/public/images/how-to/olares/select_language.png b/docs/public/images/how-to/olares/select_language.png new file mode 100644 index 000000000..6d57d6943 Binary files /dev/null and b/docs/public/images/how-to/olares/select_language.png differ diff --git a/docs/public/images/how-to/olares/settings.jpg b/docs/public/images/how-to/olares/settings.jpg new file mode 100644 index 000000000..d438ff97d Binary files /dev/null and b/docs/public/images/how-to/olares/settings.jpg differ diff --git a/docs/public/images/how-to/olares/settings_create_account.png b/docs/public/images/how-to/olares/settings_create_account.png new file mode 100644 index 000000000..1c46fe24a Binary files /dev/null and b/docs/public/images/how-to/olares/settings_create_account.png differ diff --git a/docs/public/images/how-to/olares/settings_domain_setup.png b/docs/public/images/how-to/olares/settings_domain_setup.png new file mode 100644 index 000000000..a8ad5b68b Binary files /dev/null and b/docs/public/images/how-to/olares/settings_domain_setup.png differ diff --git a/docs/public/images/how-to/olares/settings_user_info.png b/docs/public/images/how-to/olares/settings_user_info.png new file mode 100644 index 000000000..35e7a1665 Binary files /dev/null and b/docs/public/images/how-to/olares/settings_user_info.png differ diff --git a/docs/public/images/how-to/olares/settings_users.png b/docs/public/images/how-to/olares/settings_users.png new file mode 100644 index 000000000..a40682d0a Binary files /dev/null and b/docs/public/images/how-to/olares/settings_users.png differ diff --git a/docs/public/images/how-to/olares/settings_view_backup_logs.png b/docs/public/images/how-to/olares/settings_view_backup_logs.png new file mode 100644 index 000000000..f48dbdc6f Binary files /dev/null and b/docs/public/images/how-to/olares/settings_view_backup_logs.png differ diff --git a/docs/public/images/how-to/olares/sync.jpg b/docs/public/images/how-to/olares/sync.jpg new file mode 100644 index 000000000..765454b0d Binary files /dev/null and b/docs/public/images/how-to/olares/sync.jpg differ diff --git a/docs/public/images/how-to/olares/sync_new_library.jpg b/docs/public/images/how-to/olares/sync_new_library.jpg new file mode 100644 index 000000000..6d88c44f7 Binary files /dev/null and b/docs/public/images/how-to/olares/sync_new_library.jpg differ diff --git a/docs/public/images/how-to/olares/sync_operation.jpg b/docs/public/images/how-to/olares/sync_operation.jpg new file mode 100644 index 000000000..baf806ecf Binary files /dev/null and b/docs/public/images/how-to/olares/sync_operation.jpg differ diff --git a/docs/public/images/how-to/olares/sync_share_repo.jpg b/docs/public/images/how-to/olares/sync_share_repo.jpg new file mode 100644 index 000000000..67df1bbc3 Binary files /dev/null and b/docs/public/images/how-to/olares/sync_share_repo.jpg differ diff --git a/docs/public/images/how-to/olares/update_successed.png b/docs/public/images/how-to/olares/update_successed.png new file mode 100644 index 000000000..e08241fba Binary files /dev/null and b/docs/public/images/how-to/olares/update_successed.png differ diff --git a/docs/public/images/how-to/olares/upgrade.png b/docs/public/images/how-to/olares/upgrade.png new file mode 100644 index 000000000..428b47d98 Binary files /dev/null and b/docs/public/images/how-to/olares/upgrade.png differ diff --git a/docs/public/images/how-to/olares/vault.jpg b/docs/public/images/how-to/olares/vault.jpg new file mode 100644 index 000000000..9103fc64e Binary files /dev/null and b/docs/public/images/how-to/olares/vault.jpg differ diff --git a/docs/public/images/how-to/olares/vault2.jpg b/docs/public/images/how-to/olares/vault2.jpg new file mode 100644 index 000000000..1b16e4260 Binary files /dev/null and b/docs/public/images/how-to/olares/vault2.jpg differ diff --git a/docs/public/images/how-to/olares/vault_accepted.jpg b/docs/public/images/how-to/olares/vault_accepted.jpg new file mode 100644 index 000000000..e2cb7299d Binary files /dev/null and b/docs/public/images/how-to/olares/vault_accepted.jpg differ diff --git a/docs/public/images/how-to/olares/vault_add_fields.jpg b/docs/public/images/how-to/olares/vault_add_fields.jpg new file mode 100644 index 000000000..81651b650 Binary files /dev/null and b/docs/public/images/how-to/olares/vault_add_fields.jpg differ diff --git a/docs/public/images/how-to/olares/vault_dialog.jpg b/docs/public/images/how-to/olares/vault_dialog.jpg new file mode 100644 index 000000000..dac357d1b Binary files /dev/null and b/docs/public/images/how-to/olares/vault_dialog.jpg differ diff --git a/docs/public/images/how-to/olares/vault_edit.jpg b/docs/public/images/how-to/olares/vault_edit.jpg new file mode 100644 index 000000000..8678a6559 Binary files /dev/null and b/docs/public/images/how-to/olares/vault_edit.jpg differ diff --git a/docs/public/images/how-to/olares/vault_invite.jpg b/docs/public/images/how-to/olares/vault_invite.jpg new file mode 100644 index 000000000..49d492c5e Binary files /dev/null and b/docs/public/images/how-to/olares/vault_invite.jpg differ diff --git a/docs/public/images/how-to/olares/vault_new_vault.jpg b/docs/public/images/how-to/olares/vault_new_vault.jpg new file mode 100644 index 000000000..d1b3a5f20 Binary files /dev/null and b/docs/public/images/how-to/olares/vault_new_vault.jpg differ diff --git a/docs/public/images/how-to/olares/vault_web1.jpg b/docs/public/images/how-to/olares/vault_web1.jpg new file mode 100644 index 000000000..b1bc85e8d Binary files /dev/null and b/docs/public/images/how-to/olares/vault_web1.jpg differ diff --git a/docs/public/images/how-to/olares/vault_web2.jpg b/docs/public/images/how-to/olares/vault_web2.jpg new file mode 100644 index 000000000..c926ce8af Binary files /dev/null and b/docs/public/images/how-to/olares/vault_web2.jpg differ diff --git a/docs/public/images/how-to/olares/view_backup_logs.png b/docs/public/images/how-to/olares/view_backup_logs.png new file mode 100644 index 000000000..9fd2fb75b Binary files /dev/null and b/docs/public/images/how-to/olares/view_backup_logs.png differ diff --git a/docs/public/images/how-to/olares/wallpaper.png b/docs/public/images/how-to/olares/wallpaper.png new file mode 100644 index 000000000..39d437e3f Binary files /dev/null and b/docs/public/images/how-to/olares/wallpaper.png differ diff --git a/docs/public/images/how-to/olares/wise/feed/add-rss.jpg b/docs/public/images/how-to/olares/wise/feed/add-rss.jpg new file mode 100644 index 000000000..585d29233 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/feed/add-rss.jpg differ diff --git a/docs/public/images/how-to/olares/wise/feed/extension-rss.jpg b/docs/public/images/how-to/olares/wise/feed/extension-rss.jpg new file mode 100644 index 000000000..a0164be62 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/feed/extension-rss.jpg differ diff --git a/docs/public/images/how-to/olares/wise/feed/manage-feeds.jpg b/docs/public/images/how-to/olares/wise/feed/manage-feeds.jpg new file mode 100644 index 000000000..becfa9ea9 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/feed/manage-feeds.jpg differ diff --git a/docs/public/images/how-to/olares/wise/note/manage-tags.jpg b/docs/public/images/how-to/olares/wise/note/manage-tags.jpg new file mode 100644 index 000000000..3e80ddaa1 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/note/manage-tags.jpg differ diff --git a/docs/public/images/how-to/olares/wise/note/note.jpg b/docs/public/images/how-to/olares/wise/note/note.jpg new file mode 100644 index 000000000..f9b467ec8 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/note/note.jpg differ diff --git a/docs/public/images/how-to/olares/wise/note/tags.jpg b/docs/public/images/how-to/olares/wise/note/tags.jpg new file mode 100644 index 000000000..ce4c69ba8 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/note/tags.jpg differ diff --git a/docs/public/images/how-to/olares/wise/read/extension-articles.jpg b/docs/public/images/how-to/olares/wise/read/extension-articles.jpg new file mode 100644 index 000000000..1b25b7496 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/read/extension-articles.jpg differ diff --git a/docs/public/images/how-to/olares/wise/read/extension-pdf.jpg b/docs/public/images/how-to/olares/wise/read/extension-pdf.jpg new file mode 100644 index 000000000..5a230490f Binary files /dev/null and b/docs/public/images/how-to/olares/wise/read/extension-pdf.jpg differ diff --git a/docs/public/images/how-to/olares/wise/read/pdf-list.jpg b/docs/public/images/how-to/olares/wise/read/pdf-list.jpg new file mode 100644 index 000000000..accb31707 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/read/pdf-list.jpg differ diff --git a/docs/public/images/how-to/olares/wise/read/view-articles.jpg b/docs/public/images/how-to/olares/wise/read/view-articles.jpg new file mode 100644 index 000000000..366d029e2 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/read/view-articles.jpg differ diff --git a/docs/public/images/how-to/olares/wise/read/view-pdf.jpg b/docs/public/images/how-to/olares/wise/read/view-pdf.jpg new file mode 100644 index 000000000..7f2330ac9 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/read/view-pdf.jpg differ diff --git a/docs/public/images/how-to/olares/wise/recommend/install-recommendation.jpg b/docs/public/images/how-to/olares/wise/recommend/install-recommendation.jpg new file mode 100644 index 000000000..9e82b9197 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/recommend/install-recommendation.jpg differ diff --git a/docs/public/images/how-to/olares/wise/recommend/recommendation-log.jpg b/docs/public/images/how-to/olares/wise/recommend/recommendation-log.jpg new file mode 100644 index 000000000..d00e42100 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/recommend/recommendation-log.jpg differ diff --git a/docs/public/images/how-to/olares/wise/recommend/view-result.jpg b/docs/public/images/how-to/olares/wise/recommend/view-result.jpg new file mode 100644 index 000000000..46db794d6 Binary files /dev/null and b/docs/public/images/how-to/olares/wise/recommend/view-result.jpg differ diff --git a/docs/public/images/how-to/space/awaiting_domain.jpg b/docs/public/images/how-to/space/awaiting_domain.jpg new file mode 100644 index 000000000..f1b386681 Binary files /dev/null and b/docs/public/images/how-to/space/awaiting_domain.jpg differ diff --git a/docs/public/images/how-to/space/backup_list.jpg b/docs/public/images/how-to/space/backup_list.jpg new file mode 100644 index 000000000..5b41406bf Binary files /dev/null and b/docs/public/images/how-to/space/backup_list.jpg differ diff --git a/docs/public/images/how-to/space/basic_configuration.jpg b/docs/public/images/how-to/space/basic_configuration.jpg new file mode 100644 index 000000000..6d658fde9 Binary files /dev/null and b/docs/public/images/how-to/space/basic_configuration.jpg differ diff --git a/docs/public/images/how-to/space/confrim.jpg b/docs/public/images/how-to/space/confrim.jpg new file mode 100644 index 000000000..6d162342b Binary files /dev/null and b/docs/public/images/how-to/space/confrim.jpg differ diff --git a/docs/public/images/how-to/space/create_olares.jpg b/docs/public/images/how-to/space/create_olares.jpg new file mode 100644 index 000000000..551d4e871 Binary files /dev/null and b/docs/public/images/how-to/space/create_olares.jpg differ diff --git a/docs/public/images/how-to/space/data_on_panel_during_olares_creation.jpg b/docs/public/images/how-to/space/data_on_panel_during_olares_creation.jpg new file mode 100644 index 000000000..7ffb17138 Binary files /dev/null and b/docs/public/images/how-to/space/data_on_panel_during_olares_creation.jpg differ diff --git a/docs/public/images/how-to/space/import_account.jpg b/docs/public/images/how-to/space/import_account.jpg new file mode 100644 index 000000000..c44bbfd4a Binary files /dev/null and b/docs/public/images/how-to/space/import_account.jpg differ diff --git a/docs/public/images/how-to/space/log_out.jpg b/docs/public/images/how-to/space/log_out.jpg new file mode 100644 index 000000000..9b428373d Binary files /dev/null and b/docs/public/images/how-to/space/log_out.jpg differ diff --git a/docs/public/images/how-to/space/login.jpg b/docs/public/images/how-to/space/login.jpg new file mode 100644 index 000000000..c2c6868ad Binary files /dev/null and b/docs/public/images/how-to/space/login.jpg differ diff --git a/docs/public/images/how-to/space/management_members.jpg b/docs/public/images/how-to/space/management_members.jpg new file mode 100644 index 000000000..c43f0185b Binary files /dev/null and b/docs/public/images/how-to/space/management_members.jpg differ diff --git a/docs/public/images/how-to/space/my_olares.jpg b/docs/public/images/how-to/space/my_olares.jpg new file mode 100644 index 000000000..a68b87626 Binary files /dev/null and b/docs/public/images/how-to/space/my_olares.jpg differ diff --git a/docs/public/images/how-to/space/ns.jpg b/docs/public/images/how-to/space/ns.jpg new file mode 100644 index 000000000..d87959c1c Binary files /dev/null and b/docs/public/images/how-to/space/ns.jpg differ diff --git a/docs/public/images/how-to/space/one_time_password.jpg b/docs/public/images/how-to/space/one_time_password.jpg new file mode 100644 index 000000000..852e5547b Binary files /dev/null and b/docs/public/images/how-to/space/one_time_password.jpg differ diff --git a/docs/public/images/how-to/space/restore_backup_to_local.jpg b/docs/public/images/how-to/space/restore_backup_to_local.jpg new file mode 100644 index 000000000..0b41fbb5e Binary files /dev/null and b/docs/public/images/how-to/space/restore_backup_to_local.jpg differ diff --git a/docs/public/images/how-to/space/restore_backup_to_the_olares_space.jpg b/docs/public/images/how-to/space/restore_backup_to_the_olares_space.jpg new file mode 100644 index 000000000..1c4f6edff Binary files /dev/null and b/docs/public/images/how-to/space/restore_backup_to_the_olares_space.jpg differ diff --git a/docs/public/images/how-to/space/set_rule.jpg b/docs/public/images/how-to/space/set_rule.jpg new file mode 100644 index 000000000..09870267f Binary files /dev/null and b/docs/public/images/how-to/space/set_rule.jpg differ diff --git a/docs/public/images/how-to/space/space_login.jpg b/docs/public/images/how-to/space/space_login.jpg new file mode 100644 index 000000000..b307d387f Binary files /dev/null and b/docs/public/images/how-to/space/space_login.jpg differ diff --git a/docs/public/images/how-to/space/storage_and_network.jpg b/docs/public/images/how-to/space/storage_and_network.jpg new file mode 100644 index 000000000..c9839a994 Binary files /dev/null and b/docs/public/images/how-to/space/storage_and_network.jpg differ diff --git a/docs/public/images/how-to/space/submit_a_domain.jpg b/docs/public/images/how-to/space/submit_a_domain.jpg new file mode 100644 index 000000000..46cf5b191 Binary files /dev/null and b/docs/public/images/how-to/space/submit_a_domain.jpg differ diff --git a/docs/public/images/how-to/space/txt.jpg b/docs/public/images/how-to/space/txt.jpg new file mode 100644 index 000000000..a89342fdf Binary files /dev/null and b/docs/public/images/how-to/space/txt.jpg differ diff --git a/docs/public/images/manual/architecture-diagram.png b/docs/public/images/manual/architecture-diagram.png new file mode 100644 index 000000000..f23f2ec95 Binary files /dev/null and b/docs/public/images/manual/architecture-diagram.png differ diff --git a/docs/public/images/manual/concepts/DID-authenticate.jpg b/docs/public/images/manual/concepts/DID-authenticate.jpg new file mode 100644 index 000000000..b3282d665 Binary files /dev/null and b/docs/public/images/manual/concepts/DID-authenticate.jpg differ diff --git a/docs/public/images/manual/concepts/create-terminus-name.png b/docs/public/images/manual/concepts/create-terminus-name.png new file mode 100644 index 000000000..4207d0a72 Binary files /dev/null and b/docs/public/images/manual/concepts/create-terminus-name.png differ diff --git a/docs/public/images/manual/concepts/did.png b/docs/public/images/manual/concepts/did.png new file mode 100644 index 000000000..749a7db88 Binary files /dev/null and b/docs/public/images/manual/concepts/did.png differ diff --git a/docs/public/images/manual/concepts/image2.jpeg b/docs/public/images/manual/concepts/image2.jpeg new file mode 100644 index 000000000..da7a40fb9 Binary files /dev/null and b/docs/public/images/manual/concepts/image2.jpeg differ diff --git a/docs/public/images/manual/concepts/network-topology.jpeg b/docs/public/images/manual/concepts/network-topology.jpeg new file mode 100644 index 000000000..df15314af Binary files /dev/null and b/docs/public/images/manual/concepts/network-topology.jpeg differ diff --git a/docs/public/images/manual/concepts/reputation.jpeg b/docs/public/images/manual/concepts/reputation.jpeg new file mode 100644 index 000000000..052cc0e99 Binary files /dev/null and b/docs/public/images/manual/concepts/reputation.jpeg differ diff --git a/docs/public/images/manual/concepts/rfq.jpeg b/docs/public/images/manual/concepts/rfq.jpeg new file mode 100644 index 000000000..8bf166cae Binary files /dev/null and b/docs/public/images/manual/concepts/rfq.jpeg differ diff --git a/docs/public/images/manual/concepts/vc-diploma.jpeg b/docs/public/images/manual/concepts/vc-diploma.jpeg new file mode 100644 index 000000000..e32ee4802 Binary files /dev/null and b/docs/public/images/manual/concepts/vc-diploma.jpeg differ diff --git a/docs/public/images/manual/concepts/vc-management.png b/docs/public/images/manual/concepts/vc-management.png new file mode 100644 index 000000000..0f197f4b2 Binary files /dev/null and b/docs/public/images/manual/concepts/vc-management.png differ diff --git a/docs/public/images/manual/download-logs.png b/docs/public/images/manual/download-logs.png new file mode 100644 index 000000000..8c1ee9c3d Binary files /dev/null and b/docs/public/images/manual/download-logs.png differ diff --git a/docs/public/images/manual/generate-logs.png b/docs/public/images/manual/generate-logs.png new file mode 100644 index 000000000..a6a5b2217 Binary files /dev/null and b/docs/public/images/manual/generate-logs.png differ diff --git a/docs/public/images/manual/get-started/OTP.png b/docs/public/images/manual/get-started/OTP.png new file mode 100644 index 000000000..27252971e Binary files /dev/null and b/docs/public/images/manual/get-started/OTP.png differ diff --git a/docs/public/images/manual/get-started/access-olares-via-browser.png b/docs/public/images/manual/get-started/access-olares-via-browser.png new file mode 100644 index 000000000..fdfb465b5 Binary files /dev/null and b/docs/public/images/manual/get-started/access-olares-via-browser.png differ diff --git a/docs/public/images/manual/get-started/access-url.jpeg b/docs/public/images/manual/get-started/access-url.jpeg new file mode 100644 index 000000000..f61c95833 Binary files /dev/null and b/docs/public/images/manual/get-started/access-url.jpeg differ diff --git a/docs/public/images/manual/get-started/access-url.png b/docs/public/images/manual/get-started/access-url.png new file mode 100644 index 000000000..8f5b85bb8 Binary files /dev/null and b/docs/public/images/manual/get-started/access-url.png differ diff --git a/docs/public/images/manual/get-started/activate-olares-mdns.png b/docs/public/images/manual/get-started/activate-olares-mdns.png new file mode 100644 index 000000000..585d83a0b Binary files /dev/null and b/docs/public/images/manual/get-started/activate-olares-mdns.png differ diff --git a/docs/public/images/manual/get-started/activate-olares.png b/docs/public/images/manual/get-started/activate-olares.png new file mode 100644 index 000000000..b2b641039 Binary files /dev/null and b/docs/public/images/manual/get-started/activate-olares.png differ diff --git a/docs/public/images/manual/get-started/add-new-rule.png b/docs/public/images/manual/get-started/add-new-rule.png new file mode 100644 index 000000000..1ed820935 Binary files /dev/null and b/docs/public/images/manual/get-started/add-new-rule.png differ diff --git a/docs/public/images/manual/get-started/add-user-variable.png b/docs/public/images/manual/get-started/add-user-variable.png new file mode 100644 index 000000000..50d394c15 Binary files /dev/null and b/docs/public/images/manual/get-started/add-user-variable.png differ diff --git a/docs/public/images/manual/get-started/allow-the-connection.png b/docs/public/images/manual/get-started/allow-the-connection.png new file mode 100644 index 000000000..1492d5b9d Binary files /dev/null and b/docs/public/images/manual/get-started/allow-the-connection.png differ diff --git a/docs/public/images/manual/get-started/backup-mnemonic-phrase.png b/docs/public/images/manual/get-started/backup-mnemonic-phrase.png new file mode 100644 index 000000000..6a21cda58 Binary files /dev/null and b/docs/public/images/manual/get-started/backup-mnemonic-phrase.png differ diff --git a/docs/public/images/manual/get-started/change-execution-policy.png b/docs/public/images/manual/get-started/change-execution-policy.png new file mode 100644 index 000000000..eb82758ef Binary files /dev/null and b/docs/public/images/manual/get-started/change-execution-policy.png differ diff --git a/docs/public/images/manual/get-started/confirm-login.png b/docs/public/images/manual/get-started/confirm-login.png new file mode 100644 index 000000000..f84649df3 Binary files /dev/null and b/docs/public/images/manual/get-started/confirm-login.png differ diff --git a/docs/public/images/manual/get-started/confirm-rules.png b/docs/public/images/manual/get-started/confirm-rules.png new file mode 100644 index 000000000..cf9479267 Binary files /dev/null and b/docs/public/images/manual/get-started/confirm-rules.png differ diff --git a/docs/public/images/manual/get-started/confirm-run-powershell-as-admin.png b/docs/public/images/manual/get-started/confirm-run-powershell-as-admin.png new file mode 100644 index 000000000..c991ed8c2 Binary files /dev/null and b/docs/public/images/manual/get-started/confirm-run-powershell-as-admin.png differ diff --git a/docs/public/images/manual/get-started/create-olares-id.png b/docs/public/images/manual/get-started/create-olares-id.png new file mode 100644 index 000000000..76f5fbf55 Binary files /dev/null and b/docs/public/images/manual/get-started/create-olares-id.png differ diff --git a/docs/public/images/manual/get-started/disable-firewall.png b/docs/public/images/manual/get-started/disable-firewall.png new file mode 100644 index 000000000..0828b07b6 Binary files /dev/null and b/docs/public/images/manual/get-started/disable-firewall.png differ diff --git a/docs/public/images/manual/get-started/docker-resources-settings.png b/docs/public/images/manual/get-started/docker-resources-settings.png new file mode 100644 index 000000000..76b4d1685 Binary files /dev/null and b/docs/public/images/manual/get-started/docker-resources-settings.png differ diff --git a/docs/public/images/manual/get-started/enter-olares-id.png b/docs/public/images/manual/get-started/enter-olares-id.png new file mode 100644 index 000000000..315dccfc5 Binary files /dev/null and b/docs/public/images/manual/get-started/enter-olares-id.png differ diff --git a/docs/public/images/manual/get-started/enter-password.png b/docs/public/images/manual/get-started/enter-password.png new file mode 100644 index 000000000..7b302350e Binary files /dev/null and b/docs/public/images/manual/get-started/enter-password.png differ diff --git a/docs/public/images/manual/get-started/enter-root-user-password.png b/docs/public/images/manual/get-started/enter-root-user-password.png new file mode 100644 index 000000000..7f192ccea Binary files /dev/null and b/docs/public/images/manual/get-started/enter-root-user-password.png differ diff --git a/docs/public/images/manual/get-started/install-activate.jpeg b/docs/public/images/manual/get-started/install-activate.jpeg new file mode 100644 index 000000000..55a38e76f Binary files /dev/null and b/docs/public/images/manual/get-started/install-activate.jpeg differ diff --git a/docs/public/images/manual/get-started/log-in.png b/docs/public/images/manual/get-started/log-in.png new file mode 100644 index 000000000..e01479272 Binary files /dev/null and b/docs/public/images/manual/get-started/log-in.png differ diff --git a/docs/public/images/manual/get-started/name-the-rule.png b/docs/public/images/manual/get-started/name-the-rule.png new file mode 100644 index 000000000..f775e0344 Binary files /dev/null and b/docs/public/images/manual/get-started/name-the-rule.png differ diff --git a/docs/public/images/manual/get-started/open-wizard.png b/docs/public/images/manual/get-started/open-wizard.png new file mode 100644 index 000000000..931b54e13 Binary files /dev/null and b/docs/public/images/manual/get-started/open-wizard.png differ diff --git a/docs/public/images/manual/get-started/recreate-id.png b/docs/public/images/manual/get-started/recreate-id.png new file mode 100644 index 000000000..fdb3c6057 Binary files /dev/null and b/docs/public/images/manual/get-started/recreate-id.png differ diff --git a/docs/public/images/manual/get-started/run-installation-script.png b/docs/public/images/manual/get-started/run-installation-script.png new file mode 100644 index 000000000..80ddac464 Binary files /dev/null and b/docs/public/images/manual/get-started/run-installation-script.png differ diff --git a/docs/public/images/manual/get-started/select-advanced-settings.png b/docs/public/images/manual/get-started/select-advanced-settings.png new file mode 100644 index 000000000..be0991d0e Binary files /dev/null and b/docs/public/images/manual/get-started/select-advanced-settings.png differ diff --git a/docs/public/images/manual/get-started/select-firewall.png b/docs/public/images/manual/get-started/select-firewall.png new file mode 100644 index 000000000..8ed61eddb Binary files /dev/null and b/docs/public/images/manual/get-started/select-firewall.png differ diff --git a/docs/public/images/manual/get-started/select-language.png b/docs/public/images/manual/get-started/select-language.png new file mode 100644 index 000000000..55e0e9956 Binary files /dev/null and b/docs/public/images/manual/get-started/select-language.png differ diff --git a/docs/public/images/manual/get-started/select-port.png b/docs/public/images/manual/get-started/select-port.png new file mode 100644 index 000000000..7bde4a392 Binary files /dev/null and b/docs/public/images/manual/get-started/select-port.png differ diff --git a/docs/public/images/manual/get-started/set-up-firewall-rules.png b/docs/public/images/manual/get-started/set-up-firewall-rules.png new file mode 100644 index 000000000..2494a8d4b Binary files /dev/null and b/docs/public/images/manual/get-started/set-up-firewall-rules.png differ diff --git a/docs/public/images/manual/get-started/set-up-local-password.png b/docs/public/images/manual/get-started/set-up-local-password.png new file mode 100644 index 000000000..7bbc8bd84 Binary files /dev/null and b/docs/public/images/manual/get-started/set-up-local-password.png differ diff --git a/docs/public/images/manual/get-started/specify-port.png b/docs/public/images/manual/get-started/specify-port.png new file mode 100644 index 000000000..6ef6d4098 Binary files /dev/null and b/docs/public/images/manual/get-started/specify-port.png differ diff --git a/docs/public/images/manual/get-started/wizard-enter-password.png b/docs/public/images/manual/get-started/wizard-enter-password.png new file mode 100644 index 000000000..d20b57337 Binary files /dev/null and b/docs/public/images/manual/get-started/wizard-enter-password.png differ diff --git a/docs/public/images/manual/get-started/wizard-url-and-login-password.png b/docs/public/images/manual/get-started/wizard-url-and-login-password.png new file mode 100644 index 000000000..9daa71a78 Binary files /dev/null and b/docs/public/images/manual/get-started/wizard-url-and-login-password.png differ diff --git a/docs/public/images/manual/help/reactivate.png b/docs/public/images/manual/help/reactivate.png new file mode 100644 index 000000000..ce597b14e Binary files /dev/null and b/docs/public/images/manual/help/reactivate.png differ diff --git a/docs/public/images/manual/icons/apple-brands-solid-dark.svg b/docs/public/images/manual/icons/apple-brands-solid-dark.svg new file mode 100644 index 000000000..c2dbcd820 --- /dev/null +++ b/docs/public/images/manual/icons/apple-brands-solid-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/icons/apple-brands-solid.svg b/docs/public/images/manual/icons/apple-brands-solid.svg new file mode 100644 index 000000000..f0287714b --- /dev/null +++ b/docs/public/images/manual/icons/apple-brands-solid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/icons/linux-brands-solid-dark.svg b/docs/public/images/manual/icons/linux-brands-solid-dark.svg new file mode 100644 index 000000000..c1925faea --- /dev/null +++ b/docs/public/images/manual/icons/linux-brands-solid-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/icons/linux-brands-solid.svg b/docs/public/images/manual/icons/linux-brands-solid.svg new file mode 100644 index 000000000..861bb19c7 --- /dev/null +++ b/docs/public/images/manual/icons/linux-brands-solid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/icons/raspberry-pi-brands-solid-dark.svg b/docs/public/images/manual/icons/raspberry-pi-brands-solid-dark.svg new file mode 100644 index 000000000..eb8f1952c --- /dev/null +++ b/docs/public/images/manual/icons/raspberry-pi-brands-solid-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/icons/raspberry-pi-brands-solid.svg b/docs/public/images/manual/icons/raspberry-pi-brands-solid.svg new file mode 100644 index 000000000..da309b76a --- /dev/null +++ b/docs/public/images/manual/icons/raspberry-pi-brands-solid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/icons/windows-brands-solid-dark.svg b/docs/public/images/manual/icons/windows-brands-solid-dark.svg new file mode 100644 index 000000000..f454af6fb --- /dev/null +++ b/docs/public/images/manual/icons/windows-brands-solid-dark.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/icons/windows-brands-solid.svg b/docs/public/images/manual/icons/windows-brands-solid.svg new file mode 100644 index 000000000..58435dc83 --- /dev/null +++ b/docs/public/images/manual/icons/windows-brands-solid.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/images/manual/larepass/abnormal_state.png b/docs/public/images/manual/larepass/abnormal_state.png new file mode 100644 index 000000000..c4a0e3abe Binary files /dev/null and b/docs/public/images/manual/larepass/abnormal_state.png differ diff --git a/docs/public/images/manual/larepass/activate-olares.png b/docs/public/images/manual/larepass/activate-olares.png new file mode 100644 index 000000000..b2b641039 Binary files /dev/null and b/docs/public/images/manual/larepass/activate-olares.png differ diff --git a/docs/public/images/manual/larepass/advanced_creation.png b/docs/public/images/manual/larepass/advanced_creation.png new file mode 100644 index 000000000..1a1887a8a Binary files /dev/null and b/docs/public/images/manual/larepass/advanced_creation.png differ diff --git a/docs/public/images/manual/larepass/advanced_creation_org.png b/docs/public/images/manual/larepass/advanced_creation_org.png new file mode 100644 index 000000000..6b11ea256 Binary files /dev/null and b/docs/public/images/manual/larepass/advanced_creation_org.png differ diff --git a/docs/public/images/manual/larepass/bluetooth-network.png b/docs/public/images/manual/larepass/bluetooth-network.png new file mode 100644 index 000000000..95229fcd0 Binary files /dev/null and b/docs/public/images/manual/larepass/bluetooth-network.png differ diff --git a/docs/public/images/manual/larepass/confirm-login.png b/docs/public/images/manual/larepass/confirm-login.png new file mode 100644 index 000000000..f84649df3 Binary files /dev/null and b/docs/public/images/manual/larepass/confirm-login.png differ diff --git a/docs/public/images/manual/larepass/connection-status.jpg b/docs/public/images/manual/larepass/connection-status.jpg new file mode 100644 index 000000000..9d7645b69 Binary files /dev/null and b/docs/public/images/manual/larepass/connection-status.jpg differ diff --git a/docs/public/images/manual/larepass/create-olares-id.png b/docs/public/images/manual/larepass/create-olares-id.png new file mode 100644 index 000000000..76f5fbf55 Binary files /dev/null and b/docs/public/images/manual/larepass/create-olares-id.png differ diff --git a/docs/public/images/manual/larepass/device-control.png b/docs/public/images/manual/larepass/device-control.png new file mode 100644 index 000000000..c22971967 Binary files /dev/null and b/docs/public/images/manual/larepass/device-control.png differ diff --git a/docs/public/images/manual/larepass/individual_olares_id_vc.png b/docs/public/images/manual/larepass/individual_olares_id_vc.png new file mode 100644 index 000000000..af5d3e20b Binary files /dev/null and b/docs/public/images/manual/larepass/individual_olares_id_vc.png differ diff --git a/docs/public/images/manual/larepass/larepass.png b/docs/public/images/manual/larepass/larepass.png new file mode 100644 index 000000000..9bc660ec0 Binary files /dev/null and b/docs/public/images/manual/larepass/larepass.png differ diff --git a/docs/public/images/manual/larepass/organization_olares_id.png b/docs/public/images/manual/larepass/organization_olares_id.png new file mode 100644 index 000000000..66b873b3a Binary files /dev/null and b/docs/public/images/manual/larepass/organization_olares_id.png differ diff --git a/docs/public/images/manual/larepass/otp-larepass.jpg b/docs/public/images/manual/larepass/otp-larepass.jpg new file mode 100644 index 000000000..269a10206 Binary files /dev/null and b/docs/public/images/manual/larepass/otp-larepass.jpg differ diff --git a/docs/public/images/manual/larepass/restore-to-factory.png b/docs/public/images/manual/larepass/restore-to-factory.png new file mode 100644 index 000000000..12536723f Binary files /dev/null and b/docs/public/images/manual/larepass/restore-to-factory.png differ diff --git a/docs/public/images/manual/larepass/second-confirmation.png b/docs/public/images/manual/larepass/second-confirmation.png new file mode 100644 index 000000000..20e42c436 Binary files /dev/null and b/docs/public/images/manual/larepass/second-confirmation.png differ diff --git a/docs/public/images/manual/larepass/switch-wifi.jpg b/docs/public/images/manual/larepass/switch-wifi.jpg new file mode 100644 index 000000000..2d9bfa352 Binary files /dev/null and b/docs/public/images/manual/larepass/switch-wifi.jpg differ diff --git a/docs/public/images/manual/larepass/vpn.jpg b/docs/public/images/manual/larepass/vpn.jpg new file mode 100644 index 000000000..9e1513f6b Binary files /dev/null and b/docs/public/images/manual/larepass/vpn.jpg differ diff --git a/docs/public/images/manual/olares/2fa-github.png b/docs/public/images/manual/olares/2fa-github.png new file mode 100644 index 000000000..0108edd66 Binary files /dev/null and b/docs/public/images/manual/olares/2fa-github.png differ diff --git a/docs/public/images/manual/olares/activate-custom-domain.png b/docs/public/images/manual/olares/activate-custom-domain.png new file mode 100644 index 000000000..498c06956 Binary files /dev/null and b/docs/public/images/manual/olares/activate-custom-domain.png differ diff --git a/docs/public/images/manual/olares/add-SMB-share-path.png b/docs/public/images/manual/olares/add-SMB-share-path.png new file mode 100644 index 000000000..87ed96add Binary files /dev/null and b/docs/public/images/manual/olares/add-SMB-share-path.png differ diff --git a/docs/public/images/manual/olares/add-acl-port.png b/docs/public/images/manual/olares/add-acl-port.png new file mode 100644 index 000000000..e0dcbe0f3 Binary files /dev/null and b/docs/public/images/manual/olares/add-acl-port.png differ diff --git a/docs/public/images/manual/olares/add-filtered-view.png b/docs/public/images/manual/olares/add-filtered-view.png new file mode 100644 index 000000000..908adea61 Binary files /dev/null and b/docs/public/images/manual/olares/add-filtered-view.png differ diff --git a/docs/public/images/manual/olares/add-host.png b/docs/public/images/manual/olares/add-host.png new file mode 100644 index 000000000..78449e6bb Binary files /dev/null and b/docs/public/images/manual/olares/add-host.png differ diff --git a/docs/public/images/manual/olares/add-vault-item.png b/docs/public/images/manual/olares/add-vault-item.png new file mode 100644 index 000000000..933ef348e Binary files /dev/null and b/docs/public/images/manual/olares/add-vault-item.png differ diff --git a/docs/public/images/manual/olares/analytics.png b/docs/public/images/manual/olares/analytics.png new file mode 100644 index 000000000..5407adbc3 Binary files /dev/null and b/docs/public/images/manual/olares/analytics.png differ diff --git a/docs/public/images/manual/olares/app-entrance.png b/docs/public/images/manual/olares/app-entrance.png new file mode 100644 index 000000000..8194eb6b1 Binary files /dev/null and b/docs/public/images/manual/olares/app-entrance.png differ diff --git a/docs/public/images/manual/olares/app-status.png b/docs/public/images/manual/olares/app-status.png new file mode 100644 index 000000000..64941d863 Binary files /dev/null and b/docs/public/images/manual/olares/app-status.png differ diff --git a/docs/public/images/manual/olares/app-suspend.png b/docs/public/images/manual/olares/app-suspend.png new file mode 100644 index 000000000..4bb86c883 Binary files /dev/null and b/docs/public/images/manual/olares/app-suspend.png differ diff --git a/docs/public/images/manual/olares/applications.png b/docs/public/images/manual/olares/applications.png new file mode 100644 index 000000000..f3d1513ec Binary files /dev/null and b/docs/public/images/manual/olares/applications.png differ diff --git a/docs/public/images/manual/olares/confirm-invitation.png b/docs/public/images/manual/olares/confirm-invitation.png new file mode 100644 index 000000000..3cf782073 Binary files /dev/null and b/docs/public/images/manual/olares/confirm-invitation.png differ diff --git a/docs/public/images/manual/olares/controlhub-export-log.png b/docs/public/images/manual/olares/controlhub-export-log.png new file mode 100644 index 000000000..2b30124d4 Binary files /dev/null and b/docs/public/images/manual/olares/controlhub-export-log.png differ diff --git a/docs/public/images/manual/olares/controlhub-log.png b/docs/public/images/manual/olares/controlhub-log.png new file mode 100644 index 000000000..5b8cfbdb0 Binary files /dev/null and b/docs/public/images/manual/olares/controlhub-log.png differ diff --git a/docs/public/images/manual/olares/custom-route-id.png b/docs/public/images/manual/olares/custom-route-id.png new file mode 100644 index 000000000..4da9383c0 Binary files /dev/null and b/docs/public/images/manual/olares/custom-route-id.png differ diff --git a/docs/public/images/manual/olares/dashboard-overview.png b/docs/public/images/manual/olares/dashboard-overview.png new file mode 100644 index 000000000..001e995fa Binary files /dev/null and b/docs/public/images/manual/olares/dashboard-overview.png differ diff --git a/docs/public/images/manual/olares/desktop.png b/docs/public/images/manual/olares/desktop.png new file mode 100644 index 000000000..8a94ce8c9 Binary files /dev/null and b/docs/public/images/manual/olares/desktop.png differ diff --git a/docs/public/images/manual/olares/downloaded-media-files.png b/docs/public/images/manual/olares/downloaded-media-files.png new file mode 100644 index 000000000..35125b5d8 Binary files /dev/null and b/docs/public/images/manual/olares/downloaded-media-files.png differ diff --git a/docs/public/images/manual/olares/enable-larepass-vpn-desktop.png b/docs/public/images/manual/olares/enable-larepass-vpn-desktop.png new file mode 100644 index 000000000..e0967dafc Binary files /dev/null and b/docs/public/images/manual/olares/enable-larepass-vpn-desktop.png differ diff --git a/docs/public/images/manual/olares/export-log.png b/docs/public/images/manual/olares/export-log.png new file mode 100644 index 000000000..b8e298afa Binary files /dev/null and b/docs/public/images/manual/olares/export-log.png differ diff --git a/docs/public/images/manual/olares/files-cloud.png b/docs/public/images/manual/olares/files-cloud.png new file mode 100644 index 000000000..dafea2797 Binary files /dev/null and b/docs/public/images/manual/olares/files-cloud.png differ diff --git a/docs/public/images/manual/olares/files-display-view.png b/docs/public/images/manual/olares/files-display-view.png new file mode 100644 index 000000000..299d4bfdd Binary files /dev/null and b/docs/public/images/manual/olares/files-display-view.png differ diff --git a/docs/public/images/manual/olares/files-preview.png b/docs/public/images/manual/olares/files-preview.png new file mode 100644 index 000000000..e0d70a6c7 Binary files /dev/null and b/docs/public/images/manual/olares/files-preview.png differ diff --git a/docs/public/images/manual/olares/files-search.png b/docs/public/images/manual/olares/files-search.png new file mode 100644 index 000000000..58603a2d2 Binary files /dev/null and b/docs/public/images/manual/olares/files-search.png differ diff --git a/docs/public/images/manual/olares/files.png b/docs/public/images/manual/olares/files.png new file mode 100644 index 000000000..b0b06740b Binary files /dev/null and b/docs/public/images/manual/olares/files.png differ diff --git a/docs/public/images/manual/olares/fill-item-fields.png b/docs/public/images/manual/olares/fill-item-fields.png new file mode 100644 index 000000000..7b0360ff2 Binary files /dev/null and b/docs/public/images/manual/olares/fill-item-fields.png differ diff --git a/docs/public/images/manual/olares/filter-entries-from-feed.png b/docs/public/images/manual/olares/filter-entries-from-feed.png new file mode 100644 index 000000000..6fe38bdf1 Binary files /dev/null and b/docs/public/images/manual/olares/filter-entries-from-feed.png differ diff --git a/docs/public/images/manual/olares/for-you.png b/docs/public/images/manual/olares/for-you.png new file mode 100644 index 000000000..48d551dc1 Binary files /dev/null and b/docs/public/images/manual/olares/for-you.png differ diff --git a/docs/public/images/manual/olares/gpu-app-exclusive.png b/docs/public/images/manual/olares/gpu-app-exclusive.png new file mode 100644 index 000000000..6a47ebc39 Binary files /dev/null and b/docs/public/images/manual/olares/gpu-app-exclusive.png differ diff --git a/docs/public/images/manual/olares/gpu-memory-slicing.png b/docs/public/images/manual/olares/gpu-memory-slicing.png new file mode 100644 index 000000000..ba704fd8a Binary files /dev/null and b/docs/public/images/manual/olares/gpu-memory-slicing.png differ diff --git a/docs/public/images/manual/olares/gpu-time-slicing.png b/docs/public/images/manual/olares/gpu-time-slicing.png new file mode 100644 index 000000000..a0f8245e6 Binary files /dev/null and b/docs/public/images/manual/olares/gpu-time-slicing.png differ diff --git a/docs/public/images/manual/olares/image-management.png b/docs/public/images/manual/olares/image-management.png new file mode 100644 index 000000000..c390f7d1c Binary files /dev/null and b/docs/public/images/manual/olares/image-management.png differ diff --git a/docs/public/images/manual/olares/inbox-read-later.png b/docs/public/images/manual/olares/inbox-read-later.png new file mode 100644 index 000000000..5310def58 Binary files /dev/null and b/docs/public/images/manual/olares/inbox-read-later.png differ diff --git a/docs/public/images/manual/olares/install-recommendation.png b/docs/public/images/manual/olares/install-recommendation.png new file mode 100644 index 000000000..d2ddad525 Binary files /dev/null and b/docs/public/images/manual/olares/install-recommendation.png differ diff --git a/docs/public/images/manual/olares/invite-members.png b/docs/public/images/manual/olares/invite-members.png new file mode 100644 index 000000000..eb81006eb Binary files /dev/null and b/docs/public/images/manual/olares/invite-members.png differ diff --git a/docs/public/images/manual/olares/market-discover.png b/docs/public/images/manual/olares/market-discover.png new file mode 100644 index 000000000..1a23ad162 Binary files /dev/null and b/docs/public/images/manual/olares/market-discover.png differ diff --git a/docs/public/images/manual/olares/multiple-entrances.png b/docs/public/images/manual/olares/multiple-entrances.png new file mode 100644 index 000000000..8cb345435 Binary files /dev/null and b/docs/public/images/manual/olares/multiple-entrances.png differ diff --git a/docs/public/images/manual/olares/notes.png b/docs/public/images/manual/olares/notes.png new file mode 100644 index 000000000..a2b849329 Binary files /dev/null and b/docs/public/images/manual/olares/notes.png differ diff --git a/docs/public/images/manual/olares/olares-terminal-in-control-hub.png b/docs/public/images/manual/olares/olares-terminal-in-control-hub.png new file mode 100644 index 000000000..0b0ecf00f Binary files /dev/null and b/docs/public/images/manual/olares/olares-terminal-in-control-hub.png differ diff --git a/docs/public/images/manual/olares/overview-analytics.png b/docs/public/images/manual/olares/overview-analytics.png new file mode 100644 index 000000000..8188e07c7 Binary files /dev/null and b/docs/public/images/manual/olares/overview-analytics.png differ diff --git a/docs/public/images/manual/olares/physical-resource-monitoring.png b/docs/public/images/manual/olares/physical-resource-monitoring.png new file mode 100644 index 000000000..201bb610c Binary files /dev/null and b/docs/public/images/manual/olares/physical-resource-monitoring.png differ diff --git a/docs/public/images/manual/olares/pin-to-sidebar.png b/docs/public/images/manual/olares/pin-to-sidebar.png new file mode 100644 index 000000000..bc0f3c393 Binary files /dev/null and b/docs/public/images/manual/olares/pin-to-sidebar.png differ diff --git a/docs/public/images/manual/olares/profile.png b/docs/public/images/manual/olares/profile.png new file mode 100644 index 000000000..89b577da8 Binary files /dev/null and b/docs/public/images/manual/olares/profile.png differ diff --git a/docs/public/images/manual/olares/recommendation-algorithm-workflow.png b/docs/public/images/manual/olares/recommendation-algorithm-workflow.png new file mode 100644 index 000000000..d21ac1af9 Binary files /dev/null and b/docs/public/images/manual/olares/recommendation-algorithm-workflow.png differ diff --git a/docs/public/images/manual/olares/repo-endpoint-management.png b/docs/public/images/manual/olares/repo-endpoint-management.png new file mode 100644 index 000000000..2d319f1d2 Binary files /dev/null and b/docs/public/images/manual/olares/repo-endpoint-management.png differ diff --git a/docs/public/images/manual/olares/repo-management.png b/docs/public/images/manual/olares/repo-management.png new file mode 100644 index 000000000..04f3b967d Binary files /dev/null and b/docs/public/images/manual/olares/repo-management.png differ diff --git a/docs/public/images/manual/olares/resource-quota.png b/docs/public/images/manual/olares/resource-quota.png new file mode 100644 index 000000000..c9c6c607d Binary files /dev/null and b/docs/public/images/manual/olares/resource-quota.png differ diff --git a/docs/public/images/manual/olares/set-auth-level-to-public.png b/docs/public/images/manual/olares/set-auth-level-to-public.png new file mode 100644 index 000000000..f17395970 Binary files /dev/null and b/docs/public/images/manual/olares/set-auth-level-to-public.png differ diff --git a/docs/public/images/manual/olares/set-custom-domain.png b/docs/public/images/manual/olares/set-custom-domain.png new file mode 100644 index 000000000..10313c37b Binary files /dev/null and b/docs/public/images/manual/olares/set-custom-domain.png differ diff --git a/docs/public/images/manual/olares/share-library.png b/docs/public/images/manual/olares/share-library.png new file mode 100644 index 000000000..9bdafb7dc Binary files /dev/null and b/docs/public/images/manual/olares/share-library.png differ diff --git a/docs/public/images/manual/olares/ssh-via-vpn.png b/docs/public/images/manual/olares/ssh-via-vpn.png new file mode 100644 index 000000000..566cfd6be Binary files /dev/null and b/docs/public/images/manual/olares/ssh-via-vpn.png differ diff --git a/docs/public/images/manual/olares/system-apps.png b/docs/public/images/manual/olares/system-apps.png new file mode 100644 index 000000000..b6fd9a9fe Binary files /dev/null and b/docs/public/images/manual/olares/system-apps.png differ diff --git a/docs/public/images/manual/olares/tags.png b/docs/public/images/manual/olares/tags.png new file mode 100644 index 000000000..9e6679e52 Binary files /dev/null and b/docs/public/images/manual/olares/tags.png differ diff --git a/docs/public/images/manual/olares/update_applications.png b/docs/public/images/manual/olares/update_applications.png new file mode 100644 index 000000000..6fd2facca Binary files /dev/null and b/docs/public/images/manual/olares/update_applications.png differ diff --git a/docs/public/images/manual/olares/usage-ranking.png b/docs/public/images/manual/olares/usage-ranking.png new file mode 100644 index 000000000..57f89f59d Binary files /dev/null and b/docs/public/images/manual/olares/usage-ranking.png differ diff --git a/docs/public/images/manual/olares/vault-local-password.png b/docs/public/images/manual/olares/vault-local-password.png new file mode 100644 index 000000000..381d2f983 Binary files /dev/null and b/docs/public/images/manual/olares/vault-local-password.png differ diff --git a/docs/public/images/manual/tutorials/access-sunshine.png b/docs/public/images/manual/tutorials/access-sunshine.png new file mode 100644 index 000000000..ebbdfd7f0 Binary files /dev/null and b/docs/public/images/manual/tutorials/access-sunshine.png differ diff --git a/docs/public/images/manual/tutorials/active-host-moonlight.png b/docs/public/images/manual/tutorials/active-host-moonlight.png new file mode 100644 index 000000000..088e7596e Binary files /dev/null and b/docs/public/images/manual/tutorials/active-host-moonlight.png differ diff --git a/docs/public/images/manual/tutorials/add-domain.png b/docs/public/images/manual/tutorials/add-domain.png new file mode 100644 index 000000000..64894a7c6 Binary files /dev/null and b/docs/public/images/manual/tutorials/add-domain.png differ diff --git a/docs/public/images/manual/tutorials/bind-domain-with-org.png b/docs/public/images/manual/tutorials/bind-domain-with-org.png new file mode 100644 index 000000000..35ae42c11 Binary files /dev/null and b/docs/public/images/manual/tutorials/bind-domain-with-org.png differ diff --git a/docs/public/images/manual/tutorials/create-a-did.png b/docs/public/images/manual/tutorials/create-a-did.png new file mode 100644 index 000000000..b57a95367 Binary files /dev/null and b/docs/public/images/manual/tutorials/create-a-did.png differ diff --git a/docs/public/images/manual/tutorials/create-did.png b/docs/public/images/manual/tutorials/create-did.png new file mode 100644 index 000000000..4292aed91 Binary files /dev/null and b/docs/public/images/manual/tutorials/create-did.png differ diff --git a/docs/public/images/manual/tutorials/create-org.png b/docs/public/images/manual/tutorials/create-org.png new file mode 100644 index 000000000..6e6ca3dc6 Binary files /dev/null and b/docs/public/images/manual/tutorials/create-org.png differ diff --git a/docs/public/images/manual/tutorials/did-stage.png b/docs/public/images/manual/tutorials/did-stage.png new file mode 100644 index 000000000..809845efa Binary files /dev/null and b/docs/public/images/manual/tutorials/did-stage.png differ diff --git a/docs/public/images/manual/tutorials/domain-added.png b/docs/public/images/manual/tutorials/domain-added.png new file mode 100644 index 000000000..b5f615546 Binary files /dev/null and b/docs/public/images/manual/tutorials/domain-added.png differ diff --git a/docs/public/images/manual/tutorials/get-pin-code.png b/docs/public/images/manual/tutorials/get-pin-code.png new file mode 100644 index 000000000..fc2cc8808 Binary files /dev/null and b/docs/public/images/manual/tutorials/get-pin-code.png differ diff --git a/docs/public/images/manual/tutorials/install-comfyui.png b/docs/public/images/manual/tutorials/install-comfyui.png new file mode 100644 index 000000000..fe51e75d0 Binary files /dev/null and b/docs/public/images/manual/tutorials/install-comfyui.png differ diff --git a/docs/public/images/manual/tutorials/install-steam-client.png b/docs/public/images/manual/tutorials/install-steam-client.png new file mode 100644 index 000000000..bb84c8425 Binary files /dev/null and b/docs/public/images/manual/tutorials/install-steam-client.png differ diff --git a/docs/public/images/manual/tutorials/join-org.png b/docs/public/images/manual/tutorials/join-org.png new file mode 100644 index 000000000..e0ca7db34 Binary files /dev/null and b/docs/public/images/manual/tutorials/join-org.png differ diff --git a/docs/public/images/manual/tutorials/pin-sunshine.png b/docs/public/images/manual/tutorials/pin-sunshine.png new file mode 100644 index 000000000..27ae06824 Binary files /dev/null and b/docs/public/images/manual/tutorials/pin-sunshine.png differ diff --git a/docs/public/images/manual/tutorials/render-android-mac.png b/docs/public/images/manual/tutorials/render-android-mac.png new file mode 100644 index 000000000..2916d6c18 Binary files /dev/null and b/docs/public/images/manual/tutorials/render-android-mac.png differ diff --git a/docs/public/images/manual/tutorials/render-android-windows.png b/docs/public/images/manual/tutorials/render-android-windows.png new file mode 100644 index 000000000..005fc437b Binary files /dev/null and b/docs/public/images/manual/tutorials/render-android-windows.png differ diff --git a/docs/public/images/manual/tutorials/scan-qr-code.png b/docs/public/images/manual/tutorials/scan-qr-code.png new file mode 100644 index 000000000..b94ca0987 Binary files /dev/null and b/docs/public/images/manual/tutorials/scan-qr-code.png differ diff --git a/docs/public/images/manual/tutorials/scan-qr.png b/docs/public/images/manual/tutorials/scan-qr.png new file mode 100644 index 000000000..127165fae Binary files /dev/null and b/docs/public/images/manual/tutorials/scan-qr.png differ diff --git a/docs/public/images/manual/tutorials/set-domain-rule.png b/docs/public/images/manual/tutorials/set-domain-rule.png new file mode 100644 index 000000000..af3041c6b Binary files /dev/null and b/docs/public/images/manual/tutorials/set-domain-rule.png differ diff --git a/docs/public/images/manual/tutorials/set-steam-display.png b/docs/public/images/manual/tutorials/set-steam-display.png new file mode 100644 index 000000000..724bec52f Binary files /dev/null and b/docs/public/images/manual/tutorials/set-steam-display.png differ diff --git a/docs/public/images/manual/tutorials/steam-login.png b/docs/public/images/manual/tutorials/steam-login.png new file mode 100644 index 000000000..eaa21c6c6 Binary files /dev/null and b/docs/public/images/manual/tutorials/steam-login.png differ diff --git a/docs/public/images/manual/tutorials/steam-setting.png b/docs/public/images/manual/tutorials/steam-setting.png new file mode 100644 index 000000000..8700982aa Binary files /dev/null and b/docs/public/images/manual/tutorials/steam-setting.png differ diff --git a/docs/public/images/manual/tutorials/stream-success.png b/docs/public/images/manual/tutorials/stream-success.png new file mode 100644 index 000000000..3c9d826f8 Binary files /dev/null and b/docs/public/images/manual/tutorials/stream-success.png differ diff --git a/docs/public/images/manual/tutorials/verify-txt.png b/docs/public/images/manual/tutorials/verify-txt.png new file mode 100644 index 000000000..93bfc7015 Binary files /dev/null and b/docs/public/images/manual/tutorials/verify-txt.png differ diff --git a/docs/public/images/manual/tutorials/wise-access-rss.png b/docs/public/images/manual/tutorials/wise-access-rss.png new file mode 100644 index 000000000..f60f75661 Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-access-rss.png differ diff --git a/docs/public/images/manual/tutorials/wise-add-articles-via-share.png b/docs/public/images/manual/tutorials/wise-add-articles-via-share.png new file mode 100644 index 000000000..d34dbfbc8 Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-add-articles-via-share.png differ diff --git a/docs/public/images/manual/tutorials/wise-add-rss.png b/docs/public/images/manual/tutorials/wise-add-rss.png new file mode 100644 index 000000000..c8625ee48 Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-add-rss.png differ diff --git a/docs/public/images/manual/tutorials/wise-collect-web-content.png b/docs/public/images/manual/tutorials/wise-collect-web-content.png new file mode 100644 index 000000000..b3ee5c1ab Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-collect-web-content.png differ diff --git a/docs/public/images/manual/tutorials/wise-cookie.png b/docs/public/images/manual/tutorials/wise-cookie.png new file mode 100644 index 000000000..d32459051 Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-cookie.png differ diff --git a/docs/public/images/manual/tutorials/wise-pdf.png b/docs/public/images/manual/tutorials/wise-pdf.png new file mode 100644 index 000000000..dab1fbed2 Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-pdf.png differ diff --git a/docs/public/images/manual/tutorials/wise-search.png b/docs/public/images/manual/tutorials/wise-search.png new file mode 100644 index 000000000..78ad1832d Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-search.png differ diff --git a/docs/public/images/manual/tutorials/wise-share-to-larepass.png b/docs/public/images/manual/tutorials/wise-share-to-larepass.png new file mode 100644 index 000000000..d025725ad Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-share-to-larepass.png differ diff --git a/docs/public/images/manual/tutorials/wise-sub-podcast.png b/docs/public/images/manual/tutorials/wise-sub-podcast.png new file mode 100644 index 000000000..ec4170abc Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-sub-podcast.png differ diff --git a/docs/public/images/manual/tutorials/wise-view-web-content.png b/docs/public/images/manual/tutorials/wise-view-web-content.png new file mode 100644 index 000000000..85387f583 Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-view-web-content.png differ diff --git a/docs/public/images/manual/tutorials/wise-youtube-rss.png b/docs/public/images/manual/tutorials/wise-youtube-rss.png new file mode 100644 index 000000000..866a11fa8 Binary files /dev/null and b/docs/public/images/manual/tutorials/wise-youtube-rss.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-analyze-dependency.png b/docs/public/images/manual/use-cases/comfyui-analyze-dependency.png new file mode 100644 index 000000000..ceeb8106d Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-analyze-dependency.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-authentication-level.png b/docs/public/images/manual/use-cases/comfyui-authentication-level.png new file mode 100644 index 000000000..e807c0b38 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-authentication-level.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-change-network.png b/docs/public/images/manual/use-cases/comfyui-change-network.png new file mode 100644 index 000000000..c3c6e93db Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-change-network.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-check-network.png b/docs/public/images/manual/use-cases/comfyui-check-network.png new file mode 100644 index 000000000..71bc56d33 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-check-network.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-custom-model-download.png b/docs/public/images/manual/use-cases/comfyui-custom-model-download.png new file mode 100644 index 000000000..1ccdea2a8 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-custom-model-download.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-install-essential.png b/docs/public/images/manual/use-cases/comfyui-install-essential.png new file mode 100644 index 000000000..743d3ce45 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-install-essential.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-log.png b/docs/public/images/manual/use-cases/comfyui-log.png new file mode 100644 index 000000000..a6501a5f3 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-log.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-manage-plugin.png b/docs/public/images/manual/use-cases/comfyui-manage-plugin.png new file mode 100644 index 000000000..a6d31136e Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-manage-plugin.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-manage-python.png b/docs/public/images/manual/use-cases/comfyui-manage-python.png new file mode 100644 index 000000000..54ec9efe2 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-manage-python.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-model-library-download.png b/docs/public/images/manual/use-cases/comfyui-model-library-download.png new file mode 100644 index 000000000..9417204c9 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-model-library-download.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-reset.png b/docs/public/images/manual/use-cases/comfyui-reset.png new file mode 100644 index 000000000..e0c6458b5 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-reset.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-start.png b/docs/public/images/manual/use-cases/comfyui-start.png new file mode 100644 index 000000000..9439f3d5f Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-start.png differ diff --git a/docs/public/images/manual/use-cases/comfyui-view-network.png b/docs/public/images/manual/use-cases/comfyui-view-network.png new file mode 100644 index 000000000..71bc56d33 Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui-view-network.png differ diff --git a/docs/public/images/manual/use-cases/comfyui.png b/docs/public/images/manual/use-cases/comfyui.png new file mode 100644 index 000000000..138a7f62d Binary files /dev/null and b/docs/public/images/manual/use-cases/comfyui.png differ diff --git a/docs/public/images/manual/use-cases/dify-add-gemma2.png b/docs/public/images/manual/use-cases/dify-add-gemma2.png new file mode 100644 index 000000000..8f4f69280 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-add-gemma2.png differ diff --git a/docs/public/images/manual/use-cases/dify-add-kb-file.png b/docs/public/images/manual/use-cases/dify-add-kb-file.png new file mode 100644 index 000000000..5fefaf3db Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-add-kb-file.png differ diff --git a/docs/public/images/manual/use-cases/dify-add-knowledge-base.png b/docs/public/images/manual/use-cases/dify-add-knowledge-base.png new file mode 100644 index 000000000..703b67691 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-add-knowledge-base.png differ diff --git a/docs/public/images/manual/use-cases/dify-app-init.png b/docs/public/images/manual/use-cases/dify-app-init.png new file mode 100644 index 000000000..3c2269f16 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-app-init.png differ diff --git a/docs/public/images/manual/use-cases/dify-chat-kb.png b/docs/public/images/manual/use-cases/dify-chat-kb.png new file mode 100644 index 000000000..a02e74a00 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-chat-kb.png differ diff --git a/docs/public/images/manual/use-cases/dify-chat-with-ashia.png b/docs/public/images/manual/use-cases/dify-chat-with-ashia.png new file mode 100644 index 000000000..43b4d9cb1 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-chat-with-ashia.png differ diff --git a/docs/public/images/manual/use-cases/dify-create-app.png b/docs/public/images/manual/use-cases/dify-create-app.png new file mode 100644 index 000000000..d2cca8f74 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-create-app.png differ diff --git a/docs/public/images/manual/use-cases/dify-default-knowledge-base.png b/docs/public/images/manual/use-cases/dify-default-knowledge-base.png new file mode 100644 index 000000000..1dbc94231 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-default-knowledge-base.png differ diff --git a/docs/public/images/manual/use-cases/dify-ollama-entrance.png b/docs/public/images/manual/use-cases/dify-ollama-entrance.png new file mode 100644 index 000000000..edb5a8249 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-ollama-entrance.png differ diff --git a/docs/public/images/manual/use-cases/dify-select-model.png b/docs/public/images/manual/use-cases/dify-select-model.png new file mode 100644 index 000000000..110ed7c67 Binary files /dev/null and b/docs/public/images/manual/use-cases/dify-select-model.png differ diff --git a/docs/public/images/manual/use-cases/install-comfyui.png b/docs/public/images/manual/use-cases/install-comfyui.png new file mode 100644 index 000000000..2ecf1ab71 Binary files /dev/null and b/docs/public/images/manual/use-cases/install-comfyui.png differ diff --git a/docs/public/images/manual/use-cases/install-dify.png b/docs/public/images/manual/use-cases/install-dify.png new file mode 100644 index 000000000..c6a1e1907 Binary files /dev/null and b/docs/public/images/manual/use-cases/install-dify.png differ diff --git a/docs/public/images/manual/use-cases/install-faster-whisper.png b/docs/public/images/manual/use-cases/install-faster-whisper.png new file mode 100644 index 000000000..59e13559d Binary files /dev/null and b/docs/public/images/manual/use-cases/install-faster-whisper.png differ diff --git a/docs/public/images/manual/use-cases/install-open-webui.png b/docs/public/images/manual/use-cases/install-open-webui.png new file mode 100644 index 000000000..73ddb1d27 Binary files /dev/null and b/docs/public/images/manual/use-cases/install-open-webui.png differ diff --git a/docs/public/images/manual/use-cases/install-sd.png b/docs/public/images/manual/use-cases/install-sd.png new file mode 100644 index 000000000..5017560c8 Binary files /dev/null and b/docs/public/images/manual/use-cases/install-sd.png differ diff --git a/docs/public/images/manual/use-cases/install-searxng.png b/docs/public/images/manual/use-cases/install-searxng.png new file mode 100644 index 000000000..e92374115 Binary files /dev/null and b/docs/public/images/manual/use-cases/install-searxng.png differ diff --git a/docs/public/images/manual/use-cases/jellyfin.png b/docs/public/images/manual/use-cases/jellyfin.png new file mode 100644 index 000000000..fd0a2b127 Binary files /dev/null and b/docs/public/images/manual/use-cases/jellyfin.png differ diff --git a/docs/public/images/manual/use-cases/krita-comfyui-connected.png b/docs/public/images/manual/use-cases/krita-comfyui-connected.png new file mode 100644 index 000000000..31466a53f Binary files /dev/null and b/docs/public/images/manual/use-cases/krita-comfyui-connected.png differ diff --git a/docs/public/images/manual/use-cases/krita-configure-plugin.png b/docs/public/images/manual/use-cases/krita-configure-plugin.png new file mode 100644 index 000000000..a87fa63e3 Binary files /dev/null and b/docs/public/images/manual/use-cases/krita-configure-plugin.png differ diff --git a/docs/public/images/manual/use-cases/krita-enable-plugin.png b/docs/public/images/manual/use-cases/krita-enable-plugin.png new file mode 100644 index 000000000..977097a89 Binary files /dev/null and b/docs/public/images/manual/use-cases/krita-enable-plugin.png differ diff --git a/docs/public/images/manual/use-cases/krita-generate-ai-art.png b/docs/public/images/manual/use-cases/krita-generate-ai-art.png new file mode 100644 index 000000000..78bc2eda5 Binary files /dev/null and b/docs/public/images/manual/use-cases/krita-generate-ai-art.png differ diff --git a/docs/public/images/manual/use-cases/krita-import-plugin.png b/docs/public/images/manual/use-cases/krita-import-plugin.png new file mode 100644 index 000000000..ec6ea66b9 Binary files /dev/null and b/docs/public/images/manual/use-cases/krita-import-plugin.png differ diff --git a/docs/public/images/manual/use-cases/krita-verify-plugin.png b/docs/public/images/manual/use-cases/krita-verify-plugin.png new file mode 100644 index 000000000..5b26ae1a0 Binary files /dev/null and b/docs/public/images/manual/use-cases/krita-verify-plugin.png differ diff --git a/docs/public/images/manual/use-cases/ollama.png b/docs/public/images/manual/use-cases/ollama.png new file mode 100644 index 000000000..b1e7b138c Binary files /dev/null and b/docs/public/images/manual/use-cases/ollama.png differ diff --git a/docs/public/images/manual/use-cases/perplexica-configurations.png b/docs/public/images/manual/use-cases/perplexica-configurations.png new file mode 100644 index 000000000..2cd977b81 Binary files /dev/null and b/docs/public/images/manual/use-cases/perplexica-configurations.png differ diff --git a/docs/public/images/manual/use-cases/perplexica-example-question.png b/docs/public/images/manual/use-cases/perplexica-example-question.png new file mode 100644 index 000000000..3b3bfe48a Binary files /dev/null and b/docs/public/images/manual/use-cases/perplexica-example-question.png differ diff --git a/docs/public/images/manual/use-cases/sd-checkpoint.png b/docs/public/images/manual/use-cases/sd-checkpoint.png new file mode 100644 index 000000000..d423a886a Binary files /dev/null and b/docs/public/images/manual/use-cases/sd-checkpoint.png differ diff --git a/docs/public/images/manual/use-cases/sd-example1.png b/docs/public/images/manual/use-cases/sd-example1.png new file mode 100644 index 000000000..4f454120a Binary files /dev/null and b/docs/public/images/manual/use-cases/sd-example1.png differ diff --git a/docs/public/images/manual/use-cases/sd-example2.png b/docs/public/images/manual/use-cases/sd-example2.png new file mode 100644 index 000000000..97d15cb86 Binary files /dev/null and b/docs/public/images/manual/use-cases/sd-example2.png differ diff --git a/docs/public/images/manual/use-cases/sd-example3.png b/docs/public/images/manual/use-cases/sd-example3.png new file mode 100644 index 000000000..40ad33d77 Binary files /dev/null and b/docs/public/images/manual/use-cases/sd-example3.png differ diff --git a/docs/public/images/manual/use-cases/sd-example4.png b/docs/public/images/manual/use-cases/sd-example4.png new file mode 100644 index 000000000..15a1b49dc Binary files /dev/null and b/docs/public/images/manual/use-cases/sd-example4.png differ diff --git a/docs/public/images/manual/use-cases/vpn-desktop.png b/docs/public/images/manual/use-cases/vpn-desktop.png new file mode 100644 index 000000000..c34906b7d Binary files /dev/null and b/docs/public/images/manual/use-cases/vpn-desktop.png differ diff --git a/docs/public/images/manual/use-cases/vpn-mobile.png b/docs/public/images/manual/use-cases/vpn-mobile.png new file mode 100644 index 000000000..214885df6 Binary files /dev/null and b/docs/public/images/manual/use-cases/vpn-mobile.png differ diff --git a/docs/public/images/overview/olares/account.jpg b/docs/public/images/overview/olares/account.jpg new file mode 100644 index 000000000..cd07be4c5 Binary files /dev/null and b/docs/public/images/overview/olares/account.jpg differ diff --git a/docs/public/images/overview/olares/image3.jpeg b/docs/public/images/overview/olares/image3.jpeg new file mode 100644 index 000000000..f839d8681 Binary files /dev/null and b/docs/public/images/overview/olares/image3.jpeg differ diff --git a/docs/public/images/overview/olares/image4.jpeg b/docs/public/images/overview/olares/image4.jpeg new file mode 100644 index 000000000..3b03a5da1 Binary files /dev/null and b/docs/public/images/overview/olares/image4.jpeg differ diff --git a/docs/public/images/overview/olares/install-windows-ip.jpeg b/docs/public/images/overview/olares/install-windows-ip.jpeg new file mode 100644 index 000000000..685c93cc7 Binary files /dev/null and b/docs/public/images/overview/olares/install-windows-ip.jpeg differ diff --git a/docs/public/images/overview/protocol/distribute.jpeg b/docs/public/images/overview/protocol/distribute.jpeg new file mode 100644 index 000000000..e4cbbac52 Binary files /dev/null and b/docs/public/images/overview/protocol/distribute.jpeg differ diff --git a/docs/public/images/overview/protocol/recommend1.jpeg b/docs/public/images/overview/protocol/recommend1.jpeg new file mode 100644 index 000000000..a4b4e7fb0 Binary files /dev/null and b/docs/public/images/overview/protocol/recommend1.jpeg differ diff --git a/docs/public/images/overview/protocol/recommend2.jpeg b/docs/public/images/overview/protocol/recommend2.jpeg new file mode 100644 index 000000000..56050912a Binary files /dev/null and b/docs/public/images/overview/protocol/recommend2.jpeg differ diff --git a/docs/public/images/overview/protocol/recommend3.jpeg b/docs/public/images/overview/protocol/recommend3.jpeg new file mode 100644 index 000000000..a2d54ecba Binary files /dev/null and b/docs/public/images/overview/protocol/recommend3.jpeg differ diff --git a/docs/public/images/overview/protocol/rfq.jpeg b/docs/public/images/overview/protocol/rfq.jpeg new file mode 100644 index 000000000..8bf166cae Binary files /dev/null and b/docs/public/images/overview/protocol/rfq.jpeg differ diff --git a/docs/public/images/overview/snowinning/did.png b/docs/public/images/overview/snowinning/did.png new file mode 100644 index 000000000..1d5771344 Binary files /dev/null and b/docs/public/images/overview/snowinning/did.png differ diff --git a/docs/public/images/overview/snowinning/image1.jpeg b/docs/public/images/overview/snowinning/image1.jpeg new file mode 100644 index 000000000..875e1ba9a Binary files /dev/null and b/docs/public/images/overview/snowinning/image1.jpeg differ diff --git a/docs/public/images/overview/snowinning/image2.jpeg b/docs/public/images/overview/snowinning/image2.jpeg new file mode 100644 index 000000000..da7a40fb9 Binary files /dev/null and b/docs/public/images/overview/snowinning/image2.jpeg differ diff --git a/docs/public/images/overview/snowinning/network-topology.jpeg b/docs/public/images/overview/snowinning/network-topology.jpeg new file mode 100644 index 000000000..df15314af Binary files /dev/null and b/docs/public/images/overview/snowinning/network-topology.jpeg differ diff --git a/docs/public/images/overview/snowinning/smart-contract-tree.jpg b/docs/public/images/overview/snowinning/smart-contract-tree.jpg new file mode 100644 index 000000000..331e775b1 Binary files /dev/null and b/docs/public/images/overview/snowinning/smart-contract-tree.jpg differ diff --git a/docs/public/images/overview/snowinning/smart-contract.jpg b/docs/public/images/overview/snowinning/smart-contract.jpg new file mode 100644 index 000000000..34afca99c Binary files /dev/null and b/docs/public/images/overview/snowinning/smart-contract.jpg differ diff --git a/docs/public/images/zh/manual/download-logs.png b/docs/public/images/zh/manual/download-logs.png new file mode 100644 index 000000000..0e74c95c1 Binary files /dev/null and b/docs/public/images/zh/manual/download-logs.png differ diff --git a/docs/public/images/zh/manual/generate-logs.png b/docs/public/images/zh/manual/generate-logs.png new file mode 100644 index 000000000..d4d381386 Binary files /dev/null and b/docs/public/images/zh/manual/generate-logs.png differ diff --git a/docs/public/images/zh/manual/get-started/access-olares-via-browser.png b/docs/public/images/zh/manual/get-started/access-olares-via-browser.png new file mode 100644 index 000000000..2ead2ccb8 Binary files /dev/null and b/docs/public/images/zh/manual/get-started/access-olares-via-browser.png differ diff --git a/docs/public/images/zh/manual/get-started/activate-olares-mdns.png b/docs/public/images/zh/manual/get-started/activate-olares-mdns.png new file mode 100644 index 000000000..2d3d5828b Binary files /dev/null and b/docs/public/images/zh/manual/get-started/activate-olares-mdns.png differ diff --git a/docs/public/images/zh/manual/get-started/enter-olares-id.png b/docs/public/images/zh/manual/get-started/enter-olares-id.png new file mode 100644 index 000000000..bd87a22d3 Binary files /dev/null and b/docs/public/images/zh/manual/get-started/enter-olares-id.png differ diff --git a/docs/public/images/zh/manual/help/reactivate.png b/docs/public/images/zh/manual/help/reactivate.png new file mode 100644 index 000000000..262263519 Binary files /dev/null and b/docs/public/images/zh/manual/help/reactivate.png differ diff --git a/docs/public/images/zh/manual/larepass/abnormal-state.jpg b/docs/public/images/zh/manual/larepass/abnormal-state.jpg new file mode 100644 index 000000000..32e453329 Binary files /dev/null and b/docs/public/images/zh/manual/larepass/abnormal-state.jpg differ diff --git a/docs/public/images/zh/manual/larepass/bluetooth-network.png b/docs/public/images/zh/manual/larepass/bluetooth-network.png new file mode 100644 index 000000000..53b5b68fc Binary files /dev/null and b/docs/public/images/zh/manual/larepass/bluetooth-network.png differ diff --git a/docs/public/images/zh/manual/larepass/device-control.png b/docs/public/images/zh/manual/larepass/device-control.png new file mode 100644 index 000000000..1a53465ec Binary files /dev/null and b/docs/public/images/zh/manual/larepass/device-control.png differ diff --git a/docs/public/images/zh/manual/larepass/switch-wifi.png b/docs/public/images/zh/manual/larepass/switch-wifi.png new file mode 100644 index 000000000..9e02656ca Binary files /dev/null and b/docs/public/images/zh/manual/larepass/switch-wifi.png differ diff --git a/docs/public/images/zh/manual/olares/app-entrance.png b/docs/public/images/zh/manual/olares/app-entrance.png new file mode 100644 index 000000000..8778e7cc7 Binary files /dev/null and b/docs/public/images/zh/manual/olares/app-entrance.png differ diff --git a/docs/public/images/zh/manual/olares/app-status.png b/docs/public/images/zh/manual/olares/app-status.png new file mode 100644 index 000000000..c51ab302a Binary files /dev/null and b/docs/public/images/zh/manual/olares/app-status.png differ diff --git a/docs/public/images/zh/manual/olares/app-suspend.png b/docs/public/images/zh/manual/olares/app-suspend.png new file mode 100644 index 000000000..39906d316 Binary files /dev/null and b/docs/public/images/zh/manual/olares/app-suspend.png differ diff --git a/docs/public/images/zh/manual/olares/controlhub-export-log.png b/docs/public/images/zh/manual/olares/controlhub-export-log.png new file mode 100644 index 000000000..7fa6cea48 Binary files /dev/null and b/docs/public/images/zh/manual/olares/controlhub-export-log.png differ diff --git a/docs/public/images/zh/manual/olares/desktop.png b/docs/public/images/zh/manual/olares/desktop.png new file mode 100644 index 000000000..b5ba878f9 Binary files /dev/null and b/docs/public/images/zh/manual/olares/desktop.png differ diff --git a/docs/public/images/zh/manual/olares/download-log.png b/docs/public/images/zh/manual/olares/download-log.png new file mode 100644 index 000000000..b1784a624 Binary files /dev/null and b/docs/public/images/zh/manual/olares/download-log.png differ diff --git a/docs/public/images/zh/manual/olares/export-container-log.jpeg b/docs/public/images/zh/manual/olares/export-container-log.jpeg new file mode 100644 index 000000000..4a9404dba Binary files /dev/null and b/docs/public/images/zh/manual/olares/export-container-log.jpeg differ diff --git a/docs/public/images/zh/manual/olares/export-log.png b/docs/public/images/zh/manual/olares/export-log.png new file mode 100644 index 000000000..70da1ba12 Binary files /dev/null and b/docs/public/images/zh/manual/olares/export-log.png differ diff --git a/docs/public/images/zh/manual/olares/files-cloud.png b/docs/public/images/zh/manual/olares/files-cloud.png new file mode 100644 index 000000000..5e2948deb Binary files /dev/null and b/docs/public/images/zh/manual/olares/files-cloud.png differ diff --git a/docs/public/images/zh/manual/olares/files.png b/docs/public/images/zh/manual/olares/files.png new file mode 100644 index 000000000..3d52ca661 Binary files /dev/null and b/docs/public/images/zh/manual/olares/files.png differ diff --git a/docs/public/images/zh/manual/olares/gpu-app-exclusive.png b/docs/public/images/zh/manual/olares/gpu-app-exclusive.png new file mode 100644 index 000000000..3d43ca1f5 Binary files /dev/null and b/docs/public/images/zh/manual/olares/gpu-app-exclusive.png differ diff --git a/docs/public/images/zh/manual/olares/gpu-memory-slicing.png b/docs/public/images/zh/manual/olares/gpu-memory-slicing.png new file mode 100644 index 000000000..608c19599 Binary files /dev/null and b/docs/public/images/zh/manual/olares/gpu-memory-slicing.png differ diff --git a/docs/public/images/zh/manual/olares/gpu-time-slicing.png b/docs/public/images/zh/manual/olares/gpu-time-slicing.png new file mode 100644 index 000000000..b5111e4f1 Binary files /dev/null and b/docs/public/images/zh/manual/olares/gpu-time-slicing.png differ diff --git a/docs/public/images/zh/manual/olares/image-management.png b/docs/public/images/zh/manual/olares/image-management.png new file mode 100644 index 000000000..4cb3f0fa0 Binary files /dev/null and b/docs/public/images/zh/manual/olares/image-management.png differ diff --git a/docs/public/images/zh/manual/olares/repo-endpoint-management.png b/docs/public/images/zh/manual/olares/repo-endpoint-management.png new file mode 100644 index 000000000..429ca4893 Binary files /dev/null and b/docs/public/images/zh/manual/olares/repo-endpoint-management.png differ diff --git a/docs/public/images/zh/manual/olares/repo-management.png b/docs/public/images/zh/manual/olares/repo-management.png new file mode 100644 index 000000000..9ceb8026a Binary files /dev/null and b/docs/public/images/zh/manual/olares/repo-management.png differ diff --git a/docs/public/images/zh/manual/tasks/activate-custom-domain.png b/docs/public/images/zh/manual/tasks/activate-custom-domain.png new file mode 100644 index 000000000..c87844318 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/activate-custom-domain.png differ diff --git a/docs/public/images/zh/manual/tasks/add-acl-port.png b/docs/public/images/zh/manual/tasks/add-acl-port.png new file mode 100644 index 000000000..e9e86595a Binary files /dev/null and b/docs/public/images/zh/manual/tasks/add-acl-port.png differ diff --git a/docs/public/images/zh/manual/tasks/add-filtered-view.png b/docs/public/images/zh/manual/tasks/add-filtered-view.png new file mode 100644 index 000000000..5f936d5a4 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/add-filtered-view.png differ diff --git a/docs/public/images/zh/manual/tasks/add-host.png b/docs/public/images/zh/manual/tasks/add-host.png new file mode 100644 index 000000000..c833d73a8 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/add-host.png differ diff --git a/docs/public/images/zh/manual/tasks/custom-route-id.png b/docs/public/images/zh/manual/tasks/custom-route-id.png new file mode 100644 index 000000000..3e3f9b466 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/custom-route-id.png differ diff --git a/docs/public/images/zh/manual/tasks/dashboard-profile-analytics.png b/docs/public/images/zh/manual/tasks/dashboard-profile-analytics.png new file mode 100644 index 000000000..b0ed3be29 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/dashboard-profile-analytics.png differ diff --git a/docs/public/images/zh/manual/tasks/enable-larepass-vpn-desktop.png b/docs/public/images/zh/manual/tasks/enable-larepass-vpn-desktop.png new file mode 100644 index 000000000..51d949263 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/enable-larepass-vpn-desktop.png differ diff --git a/docs/public/images/zh/manual/tasks/enter-custom-domain.png b/docs/public/images/zh/manual/tasks/enter-custom-domain.png new file mode 100644 index 000000000..fe55fd3b1 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/enter-custom-domain.png differ diff --git a/docs/public/images/zh/manual/tasks/filter-entries-from-feed.png b/docs/public/images/zh/manual/tasks/filter-entries-from-feed.png new file mode 100644 index 000000000..07d3b4393 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/filter-entries-from-feed.png differ diff --git a/docs/public/images/zh/manual/tasks/olares-terminal-in-control-hub.png b/docs/public/images/zh/manual/tasks/olares-terminal-in-control-hub.png new file mode 100644 index 000000000..4e6b82b62 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/olares-terminal-in-control-hub.png differ diff --git a/docs/public/images/zh/manual/tasks/pin-to-sidebar.png b/docs/public/images/zh/manual/tasks/pin-to-sidebar.png new file mode 100644 index 000000000..50bdcfda6 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/pin-to-sidebar.png differ diff --git a/docs/public/images/zh/manual/tasks/profile-example.png b/docs/public/images/zh/manual/tasks/profile-example.png new file mode 100644 index 000000000..cd516554e Binary files /dev/null and b/docs/public/images/zh/manual/tasks/profile-example.png differ diff --git a/docs/public/images/zh/manual/tasks/set-auth-level-to-public.png b/docs/public/images/zh/manual/tasks/set-auth-level-to-public.png new file mode 100644 index 000000000..328e69cc5 Binary files /dev/null and b/docs/public/images/zh/manual/tasks/set-auth-level-to-public.png differ diff --git a/docs/public/images/zh/manual/tasks/set-custom-domain.png b/docs/public/images/zh/manual/tasks/set-custom-domain.png new file mode 100644 index 000000000..ee20d62dc Binary files /dev/null and b/docs/public/images/zh/manual/tasks/set-custom-domain.png differ diff --git a/docs/public/images/zh/manual/tasks/ssh-via-vpn.png b/docs/public/images/zh/manual/tasks/ssh-via-vpn.png new file mode 100644 index 000000000..802042eaf Binary files /dev/null and b/docs/public/images/zh/manual/tasks/ssh-via-vpn.png differ diff --git a/docs/public/images/zh/manual/tutorials/confirm-restart-teable.png b/docs/public/images/zh/manual/tutorials/confirm-restart-teable.png new file mode 100644 index 000000000..b9b73789f Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/confirm-restart-teable.png differ diff --git a/docs/public/images/zh/manual/tutorials/enable-SMTP.png b/docs/public/images/zh/manual/tutorials/enable-SMTP.png new file mode 100644 index 000000000..1e486889a Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/enable-SMTP.png differ diff --git a/docs/public/images/zh/manual/tutorials/generate-AUTH.png b/docs/public/images/zh/manual/tutorials/generate-AUTH.png new file mode 100644 index 000000000..e032a3a91 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/generate-AUTH.png differ diff --git a/docs/public/images/zh/manual/tutorials/halo-SMTP.png b/docs/public/images/zh/manual/tutorials/halo-SMTP.png new file mode 100644 index 000000000..18453b317 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/halo-SMTP.png differ diff --git a/docs/public/images/zh/manual/tutorials/restart-teable.png b/docs/public/images/zh/manual/tutorials/restart-teable.png new file mode 100644 index 000000000..2f7dfeb9c Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/restart-teable.png differ diff --git a/docs/public/images/zh/manual/tutorials/steam-login.png b/docs/public/images/zh/manual/tutorials/steam-login.png new file mode 100644 index 000000000..15b2c7b09 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/steam-login.png differ diff --git a/docs/public/images/zh/manual/tutorials/steam-setting.png b/docs/public/images/zh/manual/tutorials/steam-setting.png new file mode 100644 index 000000000..1500d750f Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/steam-setting.png differ diff --git a/docs/public/images/zh/manual/tutorials/stream-success.png b/docs/public/images/zh/manual/tutorials/stream-success.png new file mode 100644 index 000000000..3c9d826f8 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/stream-success.png differ diff --git a/docs/public/images/zh/manual/tutorials/teable-config.png b/docs/public/images/zh/manual/tutorials/teable-config.png new file mode 100644 index 000000000..103ad03d0 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/teable-config.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-add-articles-via-share.png b/docs/public/images/zh/manual/tutorials/wise-add-articles-via-share.png new file mode 100644 index 000000000..071953b5a Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-add-articles-via-share.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-add-rss.png b/docs/public/images/zh/manual/tutorials/wise-add-rss.png new file mode 100644 index 000000000..a85ab2ed5 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-add-rss.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-bilibili-rss.png b/docs/public/images/zh/manual/tutorials/wise-bilibili-rss.png new file mode 100644 index 000000000..f0dd0478f Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-bilibili-rss.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-collect-web-content.png b/docs/public/images/zh/manual/tutorials/wise-collect-web-content.png new file mode 100644 index 000000000..4e1c39d7b Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-collect-web-content.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-cookie.png b/docs/public/images/zh/manual/tutorials/wise-cookie.png new file mode 100644 index 000000000..d32459051 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-cookie.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-larepass-share.png b/docs/public/images/zh/manual/tutorials/wise-larepass-share.png new file mode 100644 index 000000000..475b89632 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-larepass-share.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-pdf.png b/docs/public/images/zh/manual/tutorials/wise-pdf.png new file mode 100644 index 000000000..b3ed0cf0a Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-pdf.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-search.png b/docs/public/images/zh/manual/tutorials/wise-search.png new file mode 100644 index 000000000..52f5d824d Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-search.png differ diff --git a/docs/public/images/zh/manual/tutorials/wise-view-article.png b/docs/public/images/zh/manual/tutorials/wise-view-article.png new file mode 100644 index 000000000..b3cdc6504 Binary files /dev/null and b/docs/public/images/zh/manual/tutorials/wise-view-article.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-add-python-package.png b/docs/public/images/zh/manual/use-cases/comfyui-add-python-package.png new file mode 100644 index 000000000..9a85c617a Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-add-python-package.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-analyze-dependency.png b/docs/public/images/zh/manual/use-cases/comfyui-analyze-dependency.png new file mode 100644 index 000000000..eee021c79 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-analyze-dependency.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-authentication-level.png b/docs/public/images/zh/manual/use-cases/comfyui-authentication-level.png new file mode 100644 index 000000000..ae3608de1 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-authentication-level.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-change-network.png b/docs/public/images/zh/manual/use-cases/comfyui-change-network.png new file mode 100644 index 000000000..2bd7430b2 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-change-network.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-custom-model-download.png b/docs/public/images/zh/manual/use-cases/comfyui-custom-model-download.png new file mode 100644 index 000000000..2e9b81e67 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-custom-model-download.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-download-model .png b/docs/public/images/zh/manual/use-cases/comfyui-download-model .png new file mode 100644 index 000000000..7589177c0 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-download-model .png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-download-model.png b/docs/public/images/zh/manual/use-cases/comfyui-download-model.png new file mode 100644 index 000000000..786be2e48 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-download-model.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-install-model.png b/docs/public/images/zh/manual/use-cases/comfyui-install-model.png new file mode 100644 index 000000000..ff0ec2d95 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-install-model.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-log.png b/docs/public/images/zh/manual/use-cases/comfyui-log.png new file mode 100644 index 000000000..e9dfa4150 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-log.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-maintain.png b/docs/public/images/zh/manual/use-cases/comfyui-maintain.png new file mode 100644 index 000000000..fef04998a Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-maintain.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-manage-plugin.png b/docs/public/images/zh/manual/use-cases/comfyui-manage-plugin.png new file mode 100644 index 000000000..1df810f13 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-manage-plugin.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-manage-python.png b/docs/public/images/zh/manual/use-cases/comfyui-manage-python.png new file mode 100644 index 000000000..03f63a321 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-manage-python.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-missing-model.png b/docs/public/images/zh/manual/use-cases/comfyui-missing-model.png new file mode 100644 index 000000000..ca34e5b3b Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-missing-model.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-model-library-download.png b/docs/public/images/zh/manual/use-cases/comfyui-model-library-download.png new file mode 100644 index 000000000..dce9d6b33 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-model-library-download.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-reset.png b/docs/public/images/zh/manual/use-cases/comfyui-reset.png new file mode 100644 index 000000000..bc32781dc Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-reset.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-start.png b/docs/public/images/zh/manual/use-cases/comfyui-start.png new file mode 100644 index 000000000..212037577 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-start.png differ diff --git a/docs/public/images/zh/manual/use-cases/comfyui-view-network.png b/docs/public/images/zh/manual/use-cases/comfyui-view-network.png new file mode 100644 index 000000000..f3dc748f2 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/comfyui-view-network.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-add-gemma2.png b/docs/public/images/zh/manual/use-cases/dify-add-gemma2.png new file mode 100644 index 000000000..f095dc982 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-add-gemma2.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-add-kb-file.png b/docs/public/images/zh/manual/use-cases/dify-add-kb-file.png new file mode 100644 index 000000000..a22ce05e1 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-add-kb-file.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-add-knowledge-base.png b/docs/public/images/zh/manual/use-cases/dify-add-knowledge-base.png new file mode 100644 index 000000000..ed1f636dd Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-add-knowledge-base.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-app-init.png b/docs/public/images/zh/manual/use-cases/dify-app-init.png new file mode 100644 index 000000000..24b2db435 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-app-init.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-chat-kb.png b/docs/public/images/zh/manual/use-cases/dify-chat-kb.png new file mode 100644 index 000000000..575ce8018 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-chat-kb.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-chat-with-ashia.png b/docs/public/images/zh/manual/use-cases/dify-chat-with-ashia.png new file mode 100644 index 000000000..d9e127e65 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-chat-with-ashia.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-create-app.png b/docs/public/images/zh/manual/use-cases/dify-create-app.png new file mode 100644 index 000000000..1e7c5aa0d Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-create-app.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-default-knowledge-base.png b/docs/public/images/zh/manual/use-cases/dify-default-knowledge-base.png new file mode 100644 index 000000000..d5ce76bb7 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-default-knowledge-base.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-ollama-entrance.png b/docs/public/images/zh/manual/use-cases/dify-ollama-entrance.png new file mode 100644 index 000000000..e461bcf08 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-ollama-entrance.png differ diff --git a/docs/public/images/zh/manual/use-cases/dify-select-model.png b/docs/public/images/zh/manual/use-cases/dify-select-model.png new file mode 100644 index 000000000..6c42a938b Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/dify-select-model.png differ diff --git a/docs/public/images/zh/manual/use-cases/jellyfin-auth-level.png b/docs/public/images/zh/manual/use-cases/jellyfin-auth-level.png new file mode 100644 index 000000000..148f4fd41 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/jellyfin-auth-level.png differ diff --git a/docs/public/images/zh/manual/use-cases/jellyfin-cover.png b/docs/public/images/zh/manual/use-cases/jellyfin-cover.png new file mode 100644 index 000000000..1c3ca001f Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/jellyfin-cover.png differ diff --git a/docs/public/images/zh/manual/use-cases/jellyfin-details.png b/docs/public/images/zh/manual/use-cases/jellyfin-details.png new file mode 100644 index 000000000..4a7ad7f81 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/jellyfin-details.png differ diff --git a/docs/public/images/zh/manual/use-cases/jellyfin-login.png b/docs/public/images/zh/manual/use-cases/jellyfin-login.png new file mode 100644 index 000000000..8c972d815 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/jellyfin-login.png differ diff --git a/docs/public/images/zh/manual/use-cases/jellyfin-set-admin.png b/docs/public/images/zh/manual/use-cases/jellyfin-set-admin.png new file mode 100644 index 000000000..9e49a8397 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/jellyfin-set-admin.png differ diff --git a/docs/public/images/zh/manual/use-cases/jellyfin-set-media-library.png b/docs/public/images/zh/manual/use-cases/jellyfin-set-media-library.png new file mode 100644 index 000000000..10d0d4844 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/jellyfin-set-media-library.png differ diff --git a/docs/public/images/zh/manual/use-cases/jellyfin-video.png b/docs/public/images/zh/manual/use-cases/jellyfin-video.png new file mode 100644 index 000000000..602e641c3 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/jellyfin-video.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-add-smoke.png b/docs/public/images/zh/manual/use-cases/krita-add-smoke.png new file mode 100644 index 000000000..e730c0dae Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-add-smoke.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-enable-plugin.png b/docs/public/images/zh/manual/use-cases/krita-enable-plugin.png new file mode 100644 index 000000000..6bb56d652 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-enable-plugin.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-generate-ai-art.png b/docs/public/images/zh/manual/use-cases/krita-generate-ai-art.png new file mode 100644 index 000000000..d2b422147 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-generate-ai-art.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-img-to-img-example.png b/docs/public/images/zh/manual/use-cases/krita-img-to-img-example.png new file mode 100644 index 000000000..2083edd84 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-img-to-img-example.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-import-plugin.png b/docs/public/images/zh/manual/use-cases/krita-import-plugin.png new file mode 100644 index 000000000..e4554c051 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-import-plugin.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-inpaint.png b/docs/public/images/zh/manual/use-cases/krita-inpaint.png new file mode 100644 index 000000000..7e85a0c60 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-inpaint.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-live-art-example.png b/docs/public/images/zh/manual/use-cases/krita-live-art-example.png new file mode 100644 index 000000000..f4e6451dd Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-live-art-example.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-live-creation.png b/docs/public/images/zh/manual/use-cases/krita-live-creation.png new file mode 100644 index 000000000..d00a39938 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-live-creation.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-live-mode.png b/docs/public/images/zh/manual/use-cases/krita-live-mode.png new file mode 100644 index 000000000..f4c288a11 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-live-mode.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-sketch-inpaint.png b/docs/public/images/zh/manual/use-cases/krita-sketch-inpaint.png new file mode 100644 index 000000000..9870cf1ac Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-sketch-inpaint.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-sketch-scribble.png b/docs/public/images/zh/manual/use-cases/krita-sketch-scribble.png new file mode 100644 index 000000000..ab033287f Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-sketch-scribble.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-sketch.png b/docs/public/images/zh/manual/use-cases/krita-sketch.png new file mode 100644 index 000000000..fdde2f2f4 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-sketch.png differ diff --git a/docs/public/images/zh/manual/use-cases/krita-verify-plugin.png b/docs/public/images/zh/manual/use-cases/krita-verify-plugin.png new file mode 100644 index 000000000..ee289a558 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/krita-verify-plugin.png differ diff --git a/docs/public/images/zh/manual/use-cases/openwebui-download-model-quick.png b/docs/public/images/zh/manual/use-cases/openwebui-download-model-quick.png new file mode 100644 index 000000000..aa0780f30 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/openwebui-download-model-quick.png differ diff --git a/docs/public/images/zh/manual/use-cases/openwebui-download-model-settings.png b/docs/public/images/zh/manual/use-cases/openwebui-download-model-settings.png new file mode 100644 index 000000000..417e70617 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/openwebui-download-model-settings.png differ diff --git a/docs/public/images/zh/manual/use-cases/openwebui-faster-whisper.png b/docs/public/images/zh/manual/use-cases/openwebui-faster-whisper.png new file mode 100644 index 000000000..961c73a1f Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/openwebui-faster-whisper.png differ diff --git a/docs/public/images/zh/manual/use-cases/view-video-from-files-2.png b/docs/public/images/zh/manual/use-cases/view-video-from-files-2.png new file mode 100644 index 000000000..1b349c943 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/view-video-from-files-2.png differ diff --git a/docs/public/images/zh/manual/use-cases/view-video-from-files.png b/docs/public/images/zh/manual/use-cases/view-video-from-files.png new file mode 100644 index 000000000..cb0dd50b3 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/view-video-from-files.png differ diff --git a/docs/public/images/zh/manual/use-cases/view-video-from-larepass-desktop.png b/docs/public/images/zh/manual/use-cases/view-video-from-larepass-desktop.png new file mode 100644 index 000000000..765f93005 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/view-video-from-larepass-desktop.png differ diff --git a/docs/public/images/zh/manual/use-cases/view-video-from-larepass-mobile.png b/docs/public/images/zh/manual/use-cases/view-video-from-larepass-mobile.png new file mode 100644 index 000000000..5af8b476f Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/view-video-from-larepass-mobile.png differ diff --git a/docs/public/images/zh/manual/use-cases/vpn-desktop.png b/docs/public/images/zh/manual/use-cases/vpn-desktop.png new file mode 100644 index 000000000..e9521a681 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/vpn-desktop.png differ diff --git a/docs/public/images/zh/manual/use-cases/vpn-mobile.png b/docs/public/images/zh/manual/use-cases/vpn-mobile.png new file mode 100644 index 000000000..02f0c7579 Binary files /dev/null and b/docs/public/images/zh/manual/use-cases/vpn-mobile.png differ diff --git a/docs/settings.json b/docs/settings.json new file mode 100644 index 000000000..0766352c3 --- /dev/null +++ b/docs/settings.json @@ -0,0 +1,8 @@ +{ + "editor.defaultFormatter": "esbenp.prettier-vscode", + "editor.formatOnSave": true, + "i18n-ally.localesPaths": [ + "packages/locale", + "packages/app/src/i18n" + ] +} diff --git a/docs/space/backup-restore.md b/docs/space/backup-restore.md new file mode 100644 index 000000000..9eab2c572 --- /dev/null +++ b/docs/space/backup-restore.md @@ -0,0 +1,52 @@ +--- +description: Protect your Olares instances with cloud backup and restore features. Handle snapshots, perform restore operations, and manage storage quotas in Olares Space. +--- +# Back up and restore + +Olares Space is the official solution to back up snapshots for your Olares instances. You can restore an Olares to its most recent state whenever needed. This section provides instructions for managing backups and restores in Olares Space. + +:::tip +Each Olares is provided with 10 GB of free backup space. Any usage beyond this will be charged according to the cloud provider's pricing. +::: + +## View backup list + +The backup task list shows information for each backup task, including: + +- Initial creation time +- Most recent snapshot time +- Overall storage usage + +![alt text](/images/how-to/space/backup_list.jpg#bordered) + +Click **View Details** on a task to see its detail page. The detail page shows the storage usage since the task was created and a list of all successful snapshots. + +:::info NOTE +Currently, only restoring from the most recent snapshot is supported. +::: + +## Restore backup to the Olares Space + +![alt text](/images/how-to/space/restore_backup_to_the_olares_space.jpg#bordered) + +Restoring a snapshot to the cloud is similar to setting up a new cloud-based Olares. + +1. Set up relevant details. + + a. Select the cloud service provider and their data center location. + + b. Choose the hardware configuration for the instance. + + c. Confirm the snapshot details and enter the backup password. + +2. Understand charges for storage and bandwidth.
Each instance includes a certain amount of free storage and traffic. Any usage exceeding these quotas will incur charges. + +3. Confirm the order and complete the payment. After that, the Olares begins to install. + +:::info NOTE +During the installation process, Olares will verify the backup password. If it is incorrect, you'll be asked to re-enter the correct one. If you forget the backup password, the restoration process won't be able to continue. In this case, please return your instance and try restoring again. +::: + +:::info NOTE +To avoid conflicts or other unforeseeable problem, you must return the existing Olares that uses the same name before restoring to a cloud-based Olares. +::: \ No newline at end of file diff --git a/docs/space/billing.md b/docs/space/billing.md new file mode 100644 index 000000000..4915637a7 --- /dev/null +++ b/docs/space/billing.md @@ -0,0 +1,63 @@ +--- +description: Understand Olares Space billing system with service charges and payment workflows. Learn about cloud hosting fees, usage based pricing, and promotional credit applications. +--- +# Billing + +Olares partners with Stripe for secure payment processing. Your invoices and receipts will be sent via email, allowing you to keep records for analysis. If you have any questions during the payment process, please contact support. + +## The scope of billing + +The following services or products are billed: + +- **Hosted Olares**: Prepaid product required for setting up an Olares on a cloud provider like AWS or GCS. Pricing varies depends on the provider you choose. +- **Host instance traffic**: Postpaid charges for external traffic generated by cloud hosting out of assigned regions. +- **Worker instance**: Adding a Worker node to a hosted Olares also incurs monthly charges. Charges will be combined to the monthly bill. +- **Cloud storage**: Postpaid product storing system data via JuiceFS. Billed based on usage at the end of the billing cycle. +- **Cloud backup/restore**: Backs up host data to public storage. Billed based on usage at the end of the billing cycle. +- **Cloudflare tunnel (FRP) traffic**: Postpaid for traffic incurred by self-hosted Olares when services are accessed via public links. +- **GPU unit**: Prepaid for GPU-related services. Charges are deducted from prepaid units based on usage. + + +### Bill generation and payment scenarios + +The following actions generate bills: + +- **Creating an Olares in the cloud**: An invoice is generated immediately after you select a cloud provider and configuration. Payment is required for installation to begin. +- **Adding/Removing workers**: Bills are generated for adding workers based on the remaining time in the billing period. Similarly, refunds are calculated when removing workers. +- **Restoring a snapshot**: Equivalent to creating a new Olares, with monthly charges applied. +- **Destroying an Olares**: Fees are settled up to the destruction date. Refunds are processed as applicable. + +The monthly bill updated once per month. It includes the base subscription fees as well as any additional charges incurred during the month, such as adding a Worker, or extra traffic and storage fees. + +## How fees are deducted monthly + +Olares operates on a monthly billing cycle: +- **Automatic deduction**: Your first payment will authorize automatic deductions, with the first payment method set as default. You can disable auto-deductions from the control panel if you prefer to pay manually, but make sure to settle your bills on time to avoid service interruption. +- **Payment validity period**: For each purchase, you'll receive a bill valid for 24 hours. + + +## Use promotional credits or coupons + +We distribute trial credits or coupons through promotions. + +- Once you have received trial credits, you can view them in **Billing** > **Balance History**, and apply directly to specific products when you pay. +- Once you receive a promotional coupon codes, you can redeem them in **Billing** > **Coupons**. It could be a discount to your plans, plan subscriptions, Olares memberships, and more. + +::: tip NOTE +Trial credits or coupons are non-refundable. If you request a refund, the system will only refund your actual payment. +::: + +## FAQs + +### Will I be charged if someone accesses the WordPress site deployed on Olares? + +Yes, charges will occur from both Cloudflare for the traffic going through Cloudflare FRP tunnel. It mainly helps to hide the real IP of Olares and provides security protection against Distributed Denial of Service (DDoS) and other threats. If you host Olares on the cloud, traffic fee from your chosen vendor will apply. + + +### What happens if my bill is less than $1? + +If your total bill is under $1, it won't trigger a card charge. Instead, this amount will be added to your balance and rolled into the next bill. + +### How do I resolve a negative balance? + +A negative balance doesn't always mean you owe money. If you have a negative balance, check the **Billing** > **Balance** section for details. Pay any outstanding amounts to avoid service interruptions. diff --git a/docs/space/create-olares.md b/docs/space/create-olares.md new file mode 100644 index 000000000..81b9e75e8 --- /dev/null +++ b/docs/space/create-olares.md @@ -0,0 +1,86 @@ +--- +outline: [2, 3] +description: Set up your cloud based Olares instance in Olares Space. Configure system resources, monitor installation progress, and activate your instance with proper credentials. +--- +# Create a cloud-based Olares + +Cloud-based Olares offer a convenient deployment option, enabling you to set up an Olares environment without managing hardware directly. +This section provides a step-by-step guide to creating and managing your cloud-based Olares. + +::: tip NOTE +- The **Host Service** is currently in an invite-only beta phase. To access the cloud-based Olares, contact us for an invitation. +- If you are looking for information about setting up a self-hosted Olares, refer to the [Getting Started Guide](../manual/get-started/index.md). +::: + +## Prerequisites + +Ensure you get an Olares ID to log in to Olares Space and activate the Olares instance. + +## Create an Olares + +1. Log in to [Olares Space](https://space.olares.com/) by scanning the QR code using LarePass. +2. Navigate to the **Cluster** page and select the second option to start creating. + + ![Basic Configuration](/images/how-to/space/basic_configuration.jpg#bordered) +3. Configure the environment for installation as below: + - **Select Cloud Provider**: Choose a cloud service provider and the data center location closest to your users or workloads. + - **Hardware Configuration**: Select the instance's CPU, RAM, and storage resources. + - **Olares Version & Kubernetes Setup**: Choose the appropriate version of Olares and the Kubernetes/K3S solution to be installed. + + :::tip + If you intend to host large language models (LLMs), select the **Alibaba Cloud Hong Kong** region. Currently, it is the only region that offers instances with shared GPU services. + ::: + +4. Review the fees for storage and traffic. + + ![Storage and Network Fees](/images/how-to/space/storage_and_network.jpg#bordered) + + ::: tip NOTE + Each instance comes with a set amount of free storage and bandwidth. If your usage exceeds these quotas, additional fees will apply based on your cloud provider's pricing. + ::: +5. Review your order details, including instance configuration, selected options, and fees. +6. Complete the payment to initiate the installation process. + +## Monitor installation + +The creation and installation of your cloud-based Olares typically take around 10 minutes. During this time, you can monitor the progress and logs in real-time. + +### System statuses + +The installation follows several key stages, represented by different statuses: + +| Status | Description | +|------------------------|-------------------------------------------------------------------------------| +| **Unpaid** | Instance created but pending payment. Can be canceled. | +| **Fetching** | Payment confirmed. System is creating resources. | +| **Queuing** | Resource creation request has been submitted. | +| **Pending** | Resources created. Waiting for OS installation. | +| **Installing** | OS installation is in progress. | +| **Restoring** | OS restoration is in progress from backup. | +| **Restore_error** | Restoration failed because of incorrect snapshot password. | +| **Restarting** | System is restarting. | +| **Stopping** | System is shutting down. | +| **Starting** | System is starting up. | +| **Running** | System is operating normally. You can restart, stop, or destroy the instance. | +| **Stopped** | System is not running. You can restart or destroy the instance. | +| **Errored** | System encountered an error during resource creation or installation. | +| **Destroying** | Instance is being destroyed. | +| **Destroyed** | Instance has been destroyed. | +| **Canceled** | Instance is terminated due to cancellation or payment issues. | +| **Pending Activation** | System is waiting for activation. Will start after activations. | + +### Real-time logs + +Click **Log** to view detailed logs and monitor the installation process in real time. + +## Activate Olares + +When the installation enters the **Pending Activation** state, activate Olares: + +1. Click **Activation**. A pop-up window will display Olares ID, one-time password, and a wizard URL. + + ![One Time Password](/images/how-to/space/one_time_password.jpg#bordered) + +2. Access the wizard URL in your browser, and use the one-time password to log into Olares for the first time. +3. Change the Olares password via LarePass when prompted. +4. Follow the on-screen instructions to finish the rest of activation process. \ No newline at end of file diff --git a/docs/space/host-domain.md b/docs/space/host-domain.md new file mode 100644 index 000000000..11f27e0f0 --- /dev/null +++ b/docs/space/host-domain.md @@ -0,0 +1,80 @@ +--- +outline: [2, 3] +description: Set up custom domains in Olares Space with domain verification and DNS configuration. Create organizational Olares IDs and manage domain settings for your team. +--- + +# Set up a custom domain + +Whether you're an organizational user wanting employees to use a company-specific domain for login, or you simply wish to use a domain that you own, Olares Space allows you to set up a custom domain for easy access. + +This guide walks you through adding your own domain for your Olares system on Olares Space. + +## Prerequisites + +::: tip NOTE +A new domain can only be bound if the account is in the DID stage. If the account has already been bound with an Olares ID, it means that the account is already associated with a Domain. +::: + +Before creating and configuring your own domain, make sure that: + +- **DID account status**: Ensure your account is in DID status (i.e., not yet bound to an Olares ID). + +- **Domain Name**: Ensure you have a domain name registered through a domain registrar. The domain should not already be bound to another account in Olares Space. + +- **LarePass app**: Make sure the LarePass app is installed on your phone, as it is required for Verifiable Credential and domain management tasks. + +- **Access to the DNS settings of your domain**: This is for configuring the TXT record and NS record. + +## Add your domain + +When you have everything ready, take the steps below to add your domain in Olares Space. + +1. In the Olares Space console, navigate to **Domain** > **Domain Name Setup**, and enter your custom domain as instructed. + + ![alt text](/images/how-to/space/submit_a_domain.jpg#bordered) + +2. Add a TXT record for your domain to confirm your domain ownership. The system will verify your configuration. Once verified, the domain setup status will update automatically to **Await NS Record for Your Domain**. + + ![alt text](/images/how-to/space/txt.jpg#bordered) + +3. Add NS records to allow Olares Space to configure DNS for your domain. + + ![alt text](/images/how-to/space/ns.jpg#bordered) + + The system will verify your configuration. Once verified, the domain status will update to **Awaiting the application for the domain's Verifiable Credential**. + + ![alt text](/images/how-to/space/awaiting_domain.jpg) + +4. Launch your LarePass app, and navigate to **Organization Olares ID** > **Create an Organization**. You should see your domain listed. + +5. Click on the domain name to store the domain name on blockchain. When it's done, the domain setup status should change to **Awaiting rule configuration** on Olares Space. + +So far you have successfully associated your domain with your DID. You can now continue to [set the email invitation rule](manage-domain.md#set-email-invitation-rules) and create an organization Olares ID using the domain. + +## Create an Org Olares ID + +Now that your organization has a verified domain name, you or other members you invite can create an Olares ID using this domain. + +![org-olares-id](/images/how-to/larepass/organization_olares_id.png) + +1. In the LarePass app, navigate to **Organization Olares ID** > **Join an existing organization**. +2. Enter your organization's domain name and click **Continue**. Recheck whether your domain name has been verified and configured if an error occurs. +3. Bind the VC via your email accounts. Currently, only Gmail and Google Workspace email are supported. + +Upon completion, you will receive an Organization Olares ID. Now you can go ahead to [Activate Olares](../manual/get-started/activate-olares). + +## Domain status and processing + +After submitting a domain name, several steps are necessary to validate the entered domain. + +The table below explains different domain statuses and the corresponding actions required: + +| Status | Action Required | +|-----------------------------------------------------------------|---------------------------------------------------------------| +| Awaiting TXT record configuration | Add a TXT record | +| Awaiting NS record configuration | Add NS records | +| Awaiting the application for the domain's Verifiable Credential | Complete blockchain domain application on mobile | +| Awaiting submission of the domain's Verifiable Presentation | Complete blockchain domain application on mobile | +| Awaiting rule configuration | Set up email invitation rules for organization members | +| Binding | Wait for binding with Olares, you can access the details page | +| Allocated | Bound to Olares, you can access the details page | \ No newline at end of file diff --git a/docs/space/index.md b/docs/space/index.md new file mode 100644 index 000000000..4f83d1a7e --- /dev/null +++ b/docs/space/index.md @@ -0,0 +1,23 @@ +--- +description: Discover Olares Space platform for managed cloud hosting of Olares instances. Explore infrastructure services, host services, account management, and billing features for efficient cloud deployment. +--- +# Olares Space overview + +Olares Space is the fully managed offering of Olares on public clouds. It provides two categories of services: + +- **Infrastructure service** – Manages data backup, custom domain configuration, reverse proxy, and shared GPU resources. +- **Host service** – Hosts and manage Olares instances on public cloud platforms. + +Olares Space account is associated with your Olares IDs or DIDs. You can log in to Olares Space by scanning QR code using LarePass. + +This section walks you through usages of Olares Space, covering: + +- [Log in to/off Olares Space](manage-accounts.md) +- [Host Olares](create-olares.md) +- [Manage Olares](manage-olares.md) +- [Host custom domains](host-domain.md) +- [Manage organization domains](manage-domain.md) +- [Back up & Restore Olares](backup-restore.md) +- [Usage and Billing](billing.md) + + diff --git a/docs/space/manage-accounts.md b/docs/space/manage-accounts.md new file mode 100644 index 000000000..e71c9a6ef --- /dev/null +++ b/docs/space/manage-accounts.md @@ -0,0 +1,48 @@ +--- +description: Learn how to access and manage Olares Space accounts using LarePass authentication. +--- +# Manage accounts in Olares Space + +This guide walks you through common account operations with Olares Space, including logging in, managing multiple accounts, and logging out. + +## Log in to Olares Space + +Olares Space uses a decentralized ID (DID) or Olares ID for authentication. Make sure you already have obtained your credentials on your LarePass. + +1. In the LarePass app, select the DID or Olares ID you wish to use to log in. +2. Open https://space.olares.com/ in your browser. +3. Scan the QR code using LarePass. + +::: tip NOTE +The features and services available on Olares Space vary depending on whether you use a DID or Olares ID for login. +- **Logging in with a DID** allows you to set your own domain since no domain is associated to the account. However, you must bind the DID to an Olares ID before you can activate an Olares device. +- **Logging in with an Olares ID** enables you to create an Olares, provided the name isn't already linked to another Olares device. However, you cannot use your custom domain since your Olares ID already corresponds to a unique domain. +::: + + +## Log out + +To log out of your account: + +1. Click your avatar in the top-right corner. +2. Select **Log Out**. + +Alternatively, you can: + +1. Choose **Switch Account** from the menu. +2. Click logout next to any listed account. + + +## Manage multiple accounts + +Each Olares ID is linked to only one Olares. With multi-account management in Olares Space, you can switch between accounts effortlessly — perfect for managing multiple Olares IDs and instances. + +To add an account: + +1. Click your avatar in the top-right corner. +2. In the pop-up menu, select **Import Account**. +3. Launch LarePass, and scan the QR code to log in. + +Once you've added multiple accounts, switch between them using the **Switch Account** option in the menu. If the account is logged out, you'll be redirected to the QR code login page. + + diff --git a/docs/space/manage-domain.md b/docs/space/manage-domain.md new file mode 100644 index 000000000..a2198e1db --- /dev/null +++ b/docs/space/manage-domain.md @@ -0,0 +1,41 @@ +--- +outline: [2, 3] +description: Configure domain settings in Olares Space with email invitation rules and member management. Administrate organizational Olares IDs for seamless team collaboration. +--- + +# Manage your domain + +You must [add a domain](host-domain.md#add-your-domain) before managing it. Once your domain is set up, you can configure email invitation rules for organization members and invite them to create their own organizational **Olares ID** via email. + +## Set email invitation rules + +Most companies use a standard domain suffix for their team members' emails, like `A@myteam.com` for person A or `B@myteam.com` for person B. However, sometimes, team members might use emails in different domains. To accommodate these scenarios, Olares provides two types of rules for adding organization members' emails: + +![alt text](/images/how-to/space/set_rule.jpg#bordered) + +- **Fixed email suffix**: Use this option when all team members share the same email domain. Enter your organization's domain suffix (example: @company.com). Any email matching this suffix can be associated with your organization's Olares ID. + +- **Specified email address**: Use this option if your organization doesn't have a corporate email suffix. You need to manually add the email address for each member of the organization. + +:::info NOTE +- Currently, only Gmail is supported for both rule types. +- Emails that have been used to create organizational Olares IDs will appear in the member list and cannot be deleted. +- Emails that are manually added and have not been used to create the Olares ID appear as "unbound" and can be removed. +::: + +## Manage members + +After setting email rules, you can add or remove members under your organization. + +![alt text](/images/how-to/space/management_members.jpg#bordered) + +### Add a member + +To add a member: + +1. On the domain management page, add members to the organization by entering their email address. +2. Notify the corresponding users to use their email addresses to [create an organizational Olares ID](host-domain.md#create-an-org-olares-id). + +### Remove a member + +You can remove email addresses that haven't been used to create an Olares ID. Once an email address is associated with an organization's Olares ID, it cannot be removed. \ No newline at end of file diff --git a/docs/space/manage-olares.md b/docs/space/manage-olares.md new file mode 100644 index 000000000..4c6aa3797 --- /dev/null +++ b/docs/space/manage-olares.md @@ -0,0 +1,52 @@ +--- +outline: [2, 3] +description: Control your Olares instances through system monitoring, worker node management, and shared GPU solutions. Track storage usage, traffic consumption and maintain instance health. +--- + +# Manage Olares + +This page covers Olares management tasks in Olares Space, including monitoring system data, adding worker nodes, and managing cloud services. + +## View system status + +You can monitor the system status of Olares through **Olares Space**: + +1. In your LarePass app, go to **Settings** > **Integration**. +2. Click add in the top right corner and link your Olares Space account to the Olares device. This authorizes Olares Space's access to your system data. +3. Log into [**Olares Space**](https://space.olares.com/). +4. On the **Olares** page, view **Storage usage** and **Traffic consumption** in the system panel. + +![System Panel](/images/how-to/space/my_olares.jpg#bordered) + +:::info +For self-hosted Olares users, it's important to monitor **Traffic statistics** for intranet penetration services, and **Storage usage** for backup services. These services may incur charges based on usage. +::: + +## Add worker nodes + +For cloud Olares users, you can improve performance by adding worker nodes: + +1. Click more_horiz in the upper right corner, and select **Add Worker**. +2. On the guide page, choose your preferred hardware configuration. +3. Review the fees for storage and traffic. +4. Confirm your order and submit. + +## Return Olares + +If you no longer need your Olares service, you can return the instance by following these steps: + +1. Click more_horiz in the upper right corner. +2. Select **Destroy Olares**. +3. Confirm the action and settle your usage: + - If you are eligible for a refund, the amount will be credited back to your account balance. + - If additional payment is required, please confirm and settle the payment. + +## Shared GPU solution + +Currently, we do not offer cloud instances that include GPUs. However, for users who need GPU capabilities, we provide a shared GPU solution via rCuda. This solution is ideal for applications like Stable Diffusion, costing approximately $0.02 per image. + +::: tip NOTE +For Large Language Models (LLMs), the shared GPU solution is still under development and may require further enhancements. +::: + +If you need GPU support, please reach us on [Discord](https://discord.com/invite/BzfqrgQPDK). \ No newline at end of file diff --git a/docs/use-cases/comfyui-for-krita.md b/docs/use-cases/comfyui-for-krita.md new file mode 100644 index 000000000..a166f19ae --- /dev/null +++ b/docs/use-cases/comfyui-for-krita.md @@ -0,0 +1,101 @@ +--- +description: Learn how to integrate ComfyUI with Krita for AI-powered digital art creation. Step-by-step guide to setting up and connecting ComfyUI in Olares with Krita for seamless creative workflows. +--- +# AI art creation with ComfyUI and Krita +Running ComfyUI locally on Olares gives you the flexibility of server-side AI processing, but making it work seamlessly with your creative tools requires additional steps. Instead of confining ComfyUI to a single device, Olares allows you to extend its functionality to other machines, enabling smooth integration with tools such as Krita for editing and refinement. + +This tutorial will show you how to connect a locally hosted ComfyUI instance on Olares to Krita running on a separate computer. By combining the power of ComfyUI with Krita, you'll be able to create a streamlined, AI-driven workflow that fits naturally into your creative process. + +## Objectives +In this tutorial, you will learn how to: +- Deploy and configure ComfyUI in Olares to maximize performance and resource efficiency. +- Integrate ComfyUI with Krita to create AI-generated artwork seamlessly. + +## Understanding the components +Your AI art studio consists of three key pieces working together: + +* **ComfyUI**: The AI engine running in your Olares environment that powers image generation. +* **Krita**: Professional-grade digital art software where you'll create and edit your artwork. +* **Krita AI Diffusion Plugin**: The connector that enables seamless communication between Krita and ComfyUI. + +## What you'll need +Before starting, ensure you have: +* A working Olares installation with internet access +* A computer connected to the same local network as Olares +* Sufficient system resources (recommended: 16GB RAM for optimal performance) + +## Set up ComfyUI + +1. Install ComfyUI Shared from Market. + - For administrator users, this installs both ComfyUI Launcher (the management UI) and ComfyUI (the client UI). + - For member users, this only installs ComfyUI. + + ![Intall ComfyUI](/images/manual/use-cases/install-comfyui.png){width=40%} + +2. The administrator configures and launches the ComfyUI service from the ComfyUI Launcher. + +3. Configure ComfyUI access policy. + + a. Open Settings, navigate to **Applications** > **ComfyUI Shared** > **Entrances**. + + b. Set the **Authentication level** for ComfyUI to **Internal**. + ![ComfyUI authentication level](/images/manual/use-cases/comfyui-authentication-level.png#bordered){width=70%} +4. Launch ComfyUI from your desktop, and verify the installation by generating a sample image. +5. Copy the address of ComfyUI for next steps. +:::tip +For security, you should always run AI applications with [LarePass VPN enabled](../manual/larepass/private-network.md). +::: + +## Set up Krita + +1. Download [Krita](https://krita.org/en/download/). +2. Download the [Krita AI Diffusion plugin](https://github.com/Acly/krita-ai-diffusion/releases). +3. Launch Krita, and navigate to **Tools** > **Scripts** > **Import Python Plugin from File**, and select the downloaded ZIP package. + ![Import AI plugin](/images/manual/use-cases/krita-import-plugin.png#bordered){width=70%} +4. Confirm the plugin activation and restart Krita. +5. Open Krita, and verify the installation in **Settings** > **Configure Krita** > **Python Plugin Manager**. + ![Verify AI plugin](/images/manual/use-cases/krita-verify-plugin.png#bordered) +## Connect Krita to ComfyUI +Establish a secure connection between Krita and ComfyUI: +1. Create a new document in Krita. + :::tip + Start with a 512 x 512 pixel canvas to optimize performance and manage graphics memory efficiently. + ::: +2. Click **Settings** > **Dockers** > **AI Image Generation** to enable the plugin. You could position the panel to where it's convenient. + ![Enable AI plugin](/images/manual/use-cases/krita-enable-plugin.png#bordered) +3. Click **Configure** to access the plugin settings. + ![Configure AI plugin](/images/manual/use-cases/krita-configure-plugin.png#bordered){width=70%} +4. Set up ComfyUI connection. + + a. In **Connection**, select **Custom Server**, and paste your ComfyUI URL. + + b. Click **Connect** to verify the connection. A green "Connected" indicator confirms successful connection. + ![Connect ComfyUI](/images/manual/use-cases/krita-comfyui-connected.png#bordered) + :::info + If connection fails: + - Verify network connectivity between your computer and Olares. + - Confirm ComfyUI's authentication level is set to "Internal". + - Confirm LarePass VPN is enabled. + - Check for and disable any interfering proxy services. + - Ensure ComfyUI is running correctly on your Olares. + ::: +5. Adjust ComfyUI settings. + + a. In **Styles**, configure your preferred style templates and select appropriate model checkpoints. + + b. Keep default values for other settings unless you need specific optimizations. + +## Create AI art with text prompts +Now comes the exciting part - creating AI-generated artwork using natural language prompts. + +1. Enter your prompts in the text box, and click **Generate**. +2. Browse through the generated image variations. +3. Select a preferred result, and click **Apply** to save it to the canvas. + ![Generate AI art](/images/manual/use-cases/krita-generate-ai-art.png#bordered) +:::tip +If the results aren't quite what you want, you could: +- Create additional variations with new generations. +- Fine-tune the generation parameters. +- Refine your text prompt for more precise results. +- Experiment with different style settings. +::: diff --git a/docs/use-cases/comfyui-launcher.md b/docs/use-cases/comfyui-launcher.md new file mode 100644 index 000000000..a3419f35c --- /dev/null +++ b/docs/use-cases/comfyui-launcher.md @@ -0,0 +1,188 @@ +--- +description: Administrators' guide on how to manage ComfyUI on Olares using ComfyUI Launcher, covering controling the service, managing models, plugins, and python environments, troubleshooting and maintenance. +--- + +# Manage ComfyUI using ComfyUI Launcher + +ComfyUI Launcher is the core management tool of ComfyUI for **administrator users**. You can use it to control the running status of the ComfyUI service within the cluster, while easily managing models, plugins, runtime environment, and network configurations. + +This document guides you on how to use ComfyUI Launcher for ComfyUI service management and routine maintenance. + +## Start and stop the ComfyUI service + +As the administrator, you must start the ComfyUI service before you and other members can access it using the client interface. + +![Start/Stop ComfyUI service](/images/manual/use-cases/comfyui-start.png#bordered) + +* **Start the ComfyUI Service**: Click the **START** button in the upper-right corner to start the ComfyUI service. + + ::: tip Notes on first run + * Initial startup of ComfyUI Launcher typically takes 10-20 seconds for environment initialization. + * If the system prompts that essential models are missing, you can click the **START ANYWAY** button to launch the service. However, note that workflows may not run correctly if basic models are missing. It is recommended to download the essential model package before starting the service. + ::: + +* **Stop the ComfyUI Service**: If you are not using ComfyUI for the moment, click the **STOP** button to stop the service. This releases the VRAM and memory resources occupied by ComfyUI. + +## Manage models + +:::tip Note +Before installing models, ensure your host can access GitHub and HuggingFace. For details, refer to [Configure network](#configure-network). +::: + +ComfyUI Launcher provides flexible ways to install models. You can install the essential models with one click, manually install from Hugging Face, or copy from external sources. + +### Install essential models + +Essential models are basic models required for ComfyUI to run, including SD large models, VAE, preview decoders, and auxiliary tools models. It is recommended to install the essential package when running ComfyUI for the first time. + +1. Access the essential model package page in either of the following methods: + - In the **Missing essential models** prompt window that appears when starting the service for the first time, click **INSTALL MODELS**. + * In the **Package installation** section on the homepage, find **Essential model package**, and click **VIEW**. + +2. On the essential model installation page, click **GET ALL RESOURCES** to start the automatic installation. You can view the installation status via the progress bar below. + + ![Install resource package](/images/manual/use-cases/comfyui-install-essential.png#bordered) + +### Manually download models + +In addition to the essential models, ComfyUI Launcher also supports downloading models from the HuggingFace model library, allowing you to easily get the models you need. + + + + + + +:::tip Upload external models +If you can't find the desired model on Hugging Face, you can use **Files** to upload external models to the following directory: + + `External Devices/ai/model` +::: + +### Delete a model + +To delete a model: + +1. Navigate to **Model management** > **Model library**. +2. Under the **Installed models** section, find the model you want to delete, and click the delete button on the right to delete it permanently. + +## Manage plugins + +You can manage plugins through ComfyUI's built-in ComfyUI-Manager or use **Plugin management** in the Launcher. + +![Manage plugins](/images/manual/use-cases/comfyui-manage-plugin.png#bordered) + +### Manage available plugins + +To manage available plugins registered in ComfyUI Manager: + +1. Navigate to **Plugin management** > **Plugin Library**. +2. Under **Available plugins**, select the target plugin: + * Click the pause button to disable the currently running plugin, and click the play_circle button to resume running. + * Click the delete button to delete the plugin. + * Click the download button to download the plugin. + * Click the visibility button to view plugin details. + * Click the **UPDATE ALL PLUGINS** button to update all installed plugins. + * Click the **REFRESH** button to refresh the plugin status. + +### Download plugin from GitHub + +To install plugins directly from GitHub repositories: + +1. Navigate to **Plugin management** > **Custom Install**. +2. Enter the URL of the repository. +3. Specify the branch (optional). Use the default (usually 'main' or 'master') if not specified. +4. Click **INSTALL PLUGIN**. + +## Manage Python environment + +ComfyUI's operation relies on a set of complex Python dependency libraries. You can manage these libraries easily on the **Python dependency management** page. + +![Manage Python libraries](/images/manual/use-cases/comfyui-manage-python.png#bordered) + +### Install new dependency libraries + +To install a new dependency library: + +1. Navigate to **Python dependencies**. +2. click **INSTALL NEW PACKAGE**. +3. In the pop-up window, enter the library name and version number (optional), and then click **INSTALL**. + +### Manage installed dependency libraries + +1. Under **Installed Python packages**, find the Python library you want to manage. +2. Click the arrow_upward button on the right to update the library, or the delete button to remove it. + +### Analyze dependency installation status + +1. Under the **Dependency analysis** tab, click **ANALYZE NOW** to start analyzing. +2. From the plugins list on the left, find the problematic plugin highlighted in red, and click on it. +3. From **Dependency list**, find the missing library for the plugin, and click the **Install** button on the right. You can also click **FIX ALL** to automatically install all missing libraries. + ![Analyze dependencies](/images/manual/use-cases/comfyui-analyze-dependency.png#bordered) + +## Troubleshooting and maintenance + +ComfyUI Launcher provides tools to help diagnose and maintain the ComfyUI service. + +### Configure network + +Network connection issues can affect the download of models and plugins. Before using ComfyUI, it's recommended to check the connection status to GitHub, PyPI, and HuggingFace on the Launcher homepage. + +![Check network status](/images/manual/use-cases/comfyui-check-network.png#bordered) + +For example, if GitHub is inaccessible: + +1. Navigate to the **Network configuration**. +2. Switch the provided URLs for GitHub. +3. Click the **CHECK** button on the right to refresh the connection status. + +Repeat steps 2 and 3 until the network becomes "Accessible". + +![Switch network](/images/manual/use-cases/comfyui-change-network.png#bordered) + +### Export ComfyUI logs + +You can export logs to diagnose the current running status of ComfyUI: + +![Export Logs](/images/manual/use-cases/comfyui-log.png#bordered) + +1. In the upper-right corner of the Launcher homepage, click more_vert, then click **View logs** to view the current running log. +2. Click the refresh button to refresh the log, and the download button to download the log. + +### Reset ComfyUI configuration + +To reset ComfyUI to its initial state: + +![Reset ComfyUI](/images/manual/use-cases/comfyui-reset.png#bordered) + +1. In the upper-right corner of the Launcher's homepage, click more_vert, and select **Wipe and restore**. After a second confirmation, the Launcher will begin the wiping and restoration process. + +2. After the restoration operation is complete, restart ComfyUI for the changes to take effect. + +:::warning Exercise caution +Restoring ComfyUI is an irreversible operation. Please operate carefully. +::: + +## Discover inspirations + +Enter the **Discover** page from the left sidebar to view the latest and most trending ComfyUI models and workflows on [civit.ai](civit.ai). + +::: tip Note +Please ensure your network can properly access [civit.ai](civit.ai). +::: \ No newline at end of file diff --git a/docs/use-cases/comfyui.md b/docs/use-cases/comfyui.md new file mode 100644 index 000000000..fedb0f97a --- /dev/null +++ b/docs/use-cases/comfyui.md @@ -0,0 +1,49 @@ +--- +description: Discover how to install ComfyUI, a node-based interface for Stable Diffusion, with ease in Olares. Create reusable workflows, fine-tune image generation, and apply advanced post-processing effects. +--- +# ComfyUI + +ComfyUI is a powerful node-based interface for Stable Diffusion that transforms AI image generation into a visual programming experience. By connecting different nodes together like building blocks, you gain precise control over every aspect of the generation process - from prompts and models to post-processing effects. + +Unlike the straightforward interface of SD Web UI, ComfyUI lets you create custom workflows by connecting nodes that represent different operations. This approach gives you deeper control over the image generation pipeline while making complex operations reusable and shareable. + +## What can ComfyUI do? +ComfyUI puts advanced AI image generation capabilities at your fingertips: + +* Create reusable workflows by connecting nodes visually +* Fine-tune every aspect of the generation process +* Mix and match different models and techniques +* Save and share your custom workflows with others +* Batch process images with consistent settings +* Apply advanced post-processing effects + +## Install ComfyUI Shared + +Olares provides ComfyUI Shared to allow multiple users to share models, plugins, and workflow resources within the cluster. It also features ComfyUI Launcher, providing administrator users with a simple way to manage ComfyUI resources and runtime environments. + +::: tip Note +Starting from Olares 1.11.6, Shared applications will replace previous cluster-scoped applications. If you have installed ComfyUI for Cluster and its client, please uninstall them before installing ComfyUI Shared. +::: + +To install ComfyUI Shared: + +1. Open Olares Market, find **ComfyUI Shared**, and click **Get**. + + - The administrator will see two icons on the Olares desktop: one is the client interface for ComfyUI, and the other is ComfyUI Launcher. + + ![Install ComfyUI](/images/manual/use-cases/install-comfyui.png){width=40%} + + - Member users will only see the ComfyUI client interface on the desktop. + + :::tip Start the ComfyUI service + The administrator must start the ComfyUI service from the Launcher before all users in the cluster can access the service from the client interface. + ::: + +2. Click the ComfyUI icon to open the interface. Administrators can also enter the ComfyUI interface from the Launcher. + + ![ComfyUI Interface](/images/manual/use-cases/comfyui.png#bordered) + +## Learn more + +* [Manage ComfyUI using ComfyUI Launcher](comfyui-launcher.md) +* [Krita + ComfyUI Real-time Painting](comfyui-for-krita.md): Learn how to leverage ComfyUI to assist creative workflows in Krita. \ No newline at end of file diff --git a/docs/use-cases/dify.md b/docs/use-cases/dify.md new file mode 100644 index 000000000..0e6b74875 --- /dev/null +++ b/docs/use-cases/dify.md @@ -0,0 +1,70 @@ +--- +description: Guide to leveraging Dify on Olares for building AI applications. Learn how to deploy Dify and add personal knowledge base with ease. +--- +# Customize your local AI assistant using Dify + +Dify is an AI application development platform. It's one of the key open-source projects that Olares integrates to help you build and manage AI applications while maintaining full data ownership. Additionally, you can integrate your personal knowledge base documents into Dify for more personalized interactions. + +## Before you begin +To use local AI models on Dify, ensure you have: +- [Ollama installed](ollama.md) and running in your Olares environment. +- LassPass installed and [VPN enabled](../manual/larepass/private-network.md#enable-vpn-on-larepass) on your device. +- [Open WebUI installed](openwebui.md) with your preferred language models downloaded. + :::tip + For optimal performance, consider using lightweight yet powerful models like `gemma2` or `qwen`, which offer a good balance between speed and capability. + ::: + +## Install Dify +:::info +Starting from Olares 1.11.6, if "Dify For Cluster" or "Dify" was previously installed, uninstall them before proceeding. +::: + +1. Install "Dify Shared" from Olares Market. +2. Launch Dify from your desktop. Please ensure the admin has already installed Dify Shared. + +## Create an AI assistant app + +1. Open Dify, navigate to the **Studio** tab, and select **Create from Blank** to create an app for the AI assistant. Here, we created an agent named "Ashia". + ![Create App](/images/manual/use-cases/dify-create-app.png#bordered) + +2. Click **Go to settings** on the right to access the model provider configuration page. You can choose between remote models or locally hosted models. + ![App initial age](/images/manual/use-cases/dify-app-init.png#bordered) + +## Add Ollama as model provider + +1. Navigate to **Settings** > **Application** > **Ollama** > **Entrances**, and set the authentication level for Ollama to **Internal**. This configuration allows other applications to access Ollama services within the local network without authentication. + + ![Ollama entrance](/images/manual/use-cases/dify-ollama-entrance.png#bordered) + +2. In Dify, navigate to **Settings** > **Model Provider**. +3. Select Ollama as the model provider, with the following configurations: + - **Model Name**: Enter the model name. For example: `gemma2`. + - **Base URL**: Enter Ollama's local address: `https://39975b9a1.{username}.olares.com`. Replace `{username}` with the Olares Admin's local name. For example, `https://39975b9a1.marvin123.olares.com`. + + ![Add gemma2](/images/manual/use-cases/dify-add-gemma2.png#bordered){width=70%} + + :::tip + You can keep default values for other required fields. + ::: +4. Click **Save**. + +## Configure Ashia + +1. Navigate to Dify's **Studio** tab and enter Ashia. +2. From the model list on the right, select the Gemma2 model you just configured. + + ![Select model](/images/manual/use-cases/dify-select-model.png#bordered) +3. Click **Publish**. Now you can chat with Ashia in the **Debug & Preview** window. + + ![Chat](/images/manual/use-cases/dify-chat-with-ashia.png#bordered) + +## Set up local knowledge base +1. In Dify, navigate to the **Knowledge** tab. +2. Locate your default knowledge base. It will be named after your Olares ID and monitors the `/Documents` folder in Files. + ![Default KB](/images/manual/use-cases/dify-default-knowledge-base.png#bordered) +3. Enter `/Documents` and add documents to the knowledge base. + ![Default KB](/images/manual/use-cases/dify-add-kb-file.png#bordered) +4. In Ashia's orchestration page, click **addAdd** to add context support for Ashia. + ![Add KB](/images/manual/use-cases/dify-add-knowledge-base.png#bordered){width=70%} +5. Click **Publish**. Now try asking a domain-specific question with the help of the knowledge base. + ![Add KB](/images/manual/use-cases/dify-chat-kb.png#bordered) \ No newline at end of file diff --git a/docs/use-cases/host-cloud-android.md b/docs/use-cases/host-cloud-android.md new file mode 100644 index 000000000..cf0f40f67 --- /dev/null +++ b/docs/use-cases/host-cloud-android.md @@ -0,0 +1,279 @@ +--- +outline: [2, 3] +description: Deploy a cloud Android emulator using redroid on Olares, and access the Android host from macOS and Windows via adb and scrcpy. +--- + +# Host your cloud Android with redroid + +[redroid](https://github.com/remote-android/redroid-doc) (Remote Android) is a GPU-accelerated Android-in-Cloud (AIC) solution that integrates seamlessly with Olares. You can easily host high-performance Android instances on your Olares and access them anytime to run Android games, apps, or even automation tests. + +This tutorial walks you through installing redroid on Olares and accessing the Android instance from Windows and macOS. + +## Objectives + +By the end of this tutorial, you will learn how to: +- Install the required Linux kernel modules on the Olares host. +- Install the redroid app on Olares and get the service URL. +- Connect and operate the Android instance from Windows and macOS, using `adb` and `scrcpy`. +- Install APK apps on the Android instance. + +## Before you begin + +Make sure the following requirements are met: +- Olares is installed and running on a Linux machine. + ::: tip Configuration requirements + - redroid is only supported on Linux. Make sure your Olares instance is running on a Linux system. + - redroid is resource-intensive. For best performance, we recommend using a machine with at least an 8-core CPU and 16GB of RAM. + ::: + +- Enable [LarePass VPN](../manual/larepass/private-network.md) on your device. + +## Install dependent kernel modules + +redroid requires specific kernel modules to run on Linux. For details, refer to the [official redroid docs](https://github.com/remote-android/redroid-doc/blob/master/deploy/README.md). + +For example, on Ubuntu, you can install the required kernel modules by running the following commands in the terminal: + +```bash +sudo apt install linux-modules-extra-`uname -r` +sudo modprobe binder_linux devices="binder,hwbinder,vndbinder" +# This command might fail on newer kernels; the error can be safely ignored. +sudo modprobe ashmem_linux +``` + +## Install redroid on Olares + +redroid runs as a headless backend on Olares. To install redroid: + +1. In Olares Market, find redroid under "Utilities", and click **Get**. redroid will launch automatically after installation. + +2. Get the URL to access the redroid service: + + a. From Olares Desktop, navigate to **Settings** > **Application** > **redroid**. + + b. In **Entrances** > **Set up endpoint**, get the base domain of redroid, e.g., `beb583c3..olares.com`. + + c. Append the exported port of redroid (`46878`) to the base domain. + + Here is an example of our final URL to access the redroid service: `beb583c3.olares01.olares.com:46878`. + +## Connect to the redroid service + +To access the Android instance on Olares, you'll need to connect to the redroid service using `adb` and render the UI using `scrcpy`. + + + + + + + + +## Install APK + +Once connected, you can use `adb` to install third-party APK apps on the Android instance. + + + + + + +After installation, run `scrcpy` again to render the Android screen. Swipe up to see the installed APK. + +## Common `adb` commands + +:::tip Note +The following commands are for macOS and Linux. On Windows, replace `adb` with `adb.exe`. +::: + +```bash +# Start adb server +adb start-server + +# Connect to a device +adb connect : + +# List connected devices +adb devices + +# Disconnect a device +adb disconnect : + +# Install an APK by transport_id +adb -t 3 install your_app.apk + +# View real-time logs +adb logcat + +# Export logs to a file +adb logcat -v time > log.txt + +# Push a file to the device +adb push + +# Pull a file from the device +adb pull + +# List directory contents on device +adb shell ls + +# View file contents +adb shell cat + +# Reboot the device +adb shell reboot + +# Shut down the device +adb shell reboot -p +``` \ No newline at end of file diff --git a/docs/use-cases/index.md b/docs/use-cases/index.md new file mode 100644 index 000000000..a1f60305f --- /dev/null +++ b/docs/use-cases/index.md @@ -0,0 +1,21 @@ +--- +description: Explore practical use cases of Olares, showcasing how to leverage its features for AI workflows, creative tools, and self-hosted applications. Unlock the full potential of Olares in your environment. +--- +# Use cases and tutorials +While other guides tell you "what" and "how" with Olares, this section dives into the real-world use cases that reveal the full potential of Olares. + +From running AI models to building seamless workflows across your self-hosted services, these hands-on guides help you accomplish specific tasks and implement complete, practical solutions using your installed applications. + + \ No newline at end of file diff --git a/docs/use-cases/ollama.md b/docs/use-cases/ollama.md new file mode 100644 index 000000000..594b5ca5a --- /dev/null +++ b/docs/use-cases/ollama.md @@ -0,0 +1,83 @@ +--- +outline: [2, 3] +description: Learn how to download and manage AI models locally using Ollama CLI within the Olares environment. +--- + +# Download and run AI models locally via Ollama +Ollama is a lightweight platform that allows you to run open-source AI models like `deepseek-r1` and `gemma3` directly on your machine. Within Olares, you can integrate Ollama with graphical interfaces like Open WebUI to add more features and simplify interactions. + +This guide will show you how to set up and use Ollama CLI on Olares. + +## Before you begin +Before you start, ensure that: +- You have Olares admin privileges. +- Install LarePass and [enable LarePass VPN](../manual/larepass/private-network.md#enable-vpn-on-larepass) on your device. + +## Install Ollama + +Directly install Ollama from the Market. + +Once installation is complete, you can access Ollama terminal from the Launchpad. + +![Ollama](/images/manual/use-cases/ollama.png#bordered) +## Ollama CLI +Ollama CLI allows you to manage and interact with AI models directly. Below are the key commands and their usage: + +### Download model +:::tip Check Ollama library +If you are unsure which model to download, check the [Ollama Library](https://ollama.com/library) to explore available models. +::: +To download a model, use the following command: +```bash +ollama pull [model] +``` + +### Run model +:::tip +If the specified model has not been downloaded yet, the `ollama run` command will automatically download it before running. +::: + +To run a model, use the following command: +```bash +ollama run [model] +``` + +After running the command, you can enter queries directly into the CLI, and the model will generate responses. + +When you're finished interacting with the model, type: +```bash +/bye +``` +This will exit the session and return you to the standard terminal interface. + +### Stop model +To stop a model that is currently running, use the following command: +```bash +ollama stop [model] +``` + +### List models +To view all models installed on your system, use: +```bash +ollama list +``` + +### Remove a model +If you need to delete a model, you can use the following command: +```bash +ollama rm [model] +``` +### Show information for a model +To display detailed information about a model, use: +```bash +ollama show [model] +``` + +### List running models +To see all currently running models, use: +```bash +ollama ps +``` + +## Learn more +- [Learn how to run Ollama models with Open WebUI](openwebui.md) \ No newline at end of file diff --git a/docs/use-cases/openwebui.md b/docs/use-cases/openwebui.md new file mode 100644 index 000000000..1d815d206 --- /dev/null +++ b/docs/use-cases/openwebui.md @@ -0,0 +1,101 @@ +--- +outline: [2, 3] +description: Guide to using Open WebUI in Olares for managing Large Language Models. Learn about model management, voice interactions, and image generation capabilities with both Ollama and OpenAI-compatible APIs. +--- + +# Open WebUI + +Open WebUI provides an intuitive interface for managing Large Language Models (LLMs) that supports both Ollama and OpenAI-compatible APIs. This page helps you set up and configure Open WebUI in Olares for: + +* Model management +* Voice interactions (speech-to-text and text-to-speech) +* Image generation capabilities + +:::tip Enable LarePass VPN +Make sure your device has LassPass installed and [VPN enabled](../manual/larepass/private-network.md#enable-vpn-on-larepass) to ensure a fast and stable access. +::: + +## Installation +Ollama is required prior to launching Open WebUI: +* **For admin**: Install both "Ollama" and "Open WebUI". +* **For team members**: Ensure that "Ollama" is already installed by Olares admin, and then install "Open WebUI" only. + +![Install Ollama and Open WebUI](/images/manual/use-cases/install-open-webui.png){width=30%} + +:::info +First-time users need to create a local Open WebUI account. This account is specifically for your Olares installation and doesn't connect to external services. Note that existing Open WebUI accounts from other installations cannot be used here - you'll need to create a new one. +::: + +## Download models +:::tip +Browse available models on [Hugging Face's Chatbot Arena Leaderboard](https://huggingface.co/spaces/lmsys/chatbot-arena-leaderboard) and verify model names in the [Ollama Library](https://ollama.com/library) before downloading. +::: + +Recommended starter models for optimal performance (13B parameters or smaller): + +* `gemma2`: Google's latest efficient and powerful language model +* `llama3.2`: Meta's latest open-source vision-language model + +### Quick download +1. Click the dropdown menu, enter the model name (e.g., `llama3.2`). +2. Select **Pull from Ollama.com**. The download starts automatically. +### Download from settings +1. Click your username in the bottom left. +2. Navigate to **Admin Panel** > **Settings** > **Models**. +3. Under **Pull a model from Ollama.com**, enter the model name (e.g., `llama3.2`). +4. Click download to initiate the download. +## Configure speech features +### Speech-to-text +1. Install Faster Whisper from Market based on your role: + - Admin: Install both "Faster Whisper For Cluster" and "Faster Whisper". + - Team members: Ensure that "Faster Whisper For Cluster" is already installed by Olares admin, and install "Faster Whisper" only. + + ![Install Faster Whisper](/images/manual/use-cases/install-faster-whisper.png){width=40%} +2. Open WebUI, and navigate to **Admin Panel** > **Settings** > **Audio**. +3. Select **OpenAI** as the speech-to-text engine, with the following configurations: + - API Base URL: `http://whisper.whisper-{admin's local name}:8000/v1`. For example: `http://whisper.whisper-alice123:8000/v1`. + - API key: enter any character. +4. Enter a model variant (default: `whisper-1`). You can select from the following: + - `tiny.en` + - `tiny` + - `base.en` + - `base` + - `small.en` + - `small` + - `medium.en` + - `medium` + - `large-v1` + - `large-v2` + - `large-v3` + - `large` + - `distil-large-v2` + - `distil-medium.en` + - `distil-small.en` + - `distil-large-v3` +5. Click **Save**. +6. Launch Faster Whisper after configuration. You'll see that the model you configured in Open WebUI is automatically loaded. At this point, you can either: + - Upload audio directly to start transcription + - Adjust parameters including: + - Select different sub-models + - Choose task types + - Configure **Temperature** settings + +### Text-to-speech +1. The admin installs OpenedAI Speech from Market. This launches the service within the cluster. + :::info + "OpenedAI Speech" is a shared application and can only be installed by Olares admin. If you are a team member, ensure that the Olares admin has already installed "OpenedAI Speech". +2. Open WebUI, and navigate to **Admin Panel** > **Settings** > **Audio**. +3. Select OpenAI as the text-to-speech engine, with the following configurations: + - API Base URL: `http://openedaispeech.openedaispeech-{admin's local name}:8000/v1`. For example: `http://openedaispeech.openedaispeech-alice123:8000/v1`. + - API key: enter any character. +4. Click **Save**. + +### Text-to-image +With [SD Web UI Shared installed in your Olares environment](stable-diffusion.md#install-sd-web-ui), you can leverage Stable Diffusion's powerful image generation capabilities directly through Open WebUI. + +1. The admin installs SD Web UI Shared from Market. This launches the Stable Diffusion service within the cluster. +2. Open Open WebUI, and navigate to **Admin Panel** > **Settings** > **Images**. +3. Select **Automatic1111** as the image generation engine, with the base URL: `http://sdwebui.sdwebui--{admin's local name}:7860`. For example: `http://sdwebui.sdwebui-alice123:7860`. +4. Click cached to verify the connection. +5. Turn on **Image Generation (Experimental)**, and select your preferred text-to-image model checkpoint. +6. Click **Save**. diff --git a/docs/use-cases/perplexica.md b/docs/use-cases/perplexica.md new file mode 100644 index 000000000..4e7238a2e --- /dev/null +++ b/docs/use-cases/perplexica.md @@ -0,0 +1,45 @@ +--- +description: Explore Perplexica for advanced AI-driven data analysis and visualization with Olares. Learn how to set up Perplexica with ease. +--- +# Perplexica + +Perplexica is an open-source AI-powered search engine that provides intelligent search capabilities while maintaining user privacy. As an alternative to Perplexity AI, it combines advanced machine learning with comprehensive web search functionality to deliver accurate, source-cited answers to your queries. + +## The backend: SearSNG +SearXNG serves as the privacy-focused meta-search engine backend for Perplexica. It: +* Aggregates results from multiple search engines +* Removes tracking and preserves your privacy +* Provides clean, unbiased search results for the AI model to process + +This integration enables Perplexica to function as a complete search solution while maintaining the security of your sensitive information. + +## Before you begin +Before getting started, ensure you have: +- Ollama installed and running in your Olares environment +- [Enable LarePass VPN](../manual/larepass/private-network.md#enable-vpn-on-larepass) on your device. +- Open WebUI installed with your preferred language models downloaded + :::tip + For optimal performance, consider using lightweight yet powerful models like `gemma2`, which offer a good balance between speed and capability. + ::: +## Set up Perplexica + +1. The admin installs SearXNG from Market. + + :::info + Starting from Olares 1.11.6, if "SearXNG For Cluster" or the "SearXNG" client was previously installed, uninstall them before proceeding. + ::: + +2. Install Perplexica from Market. +3. Launch Perplexica, and click settings in the bottom left corner to open the settings window. +4. Configure your search environment with the following settings (using `gemma2` as an example): + - **Chat model Provider**: `Ollama` + - **Chat Model**: `gemma2:latest` + - **Embedding model Provider**: `Ollama` + - **Embedding Model**: `gemma2:latest` + + ![Perplexica configurations](/images/manual/use-cases/perplexica-configurations.png#bordered){width=50%} +5. Click the confirmation button to save your configuration and return to the search interface. + +Your setup is complete. Try searching for a topic you're interested in to test your new search environment. +![Perplexica example](/images/manual/use-cases/perplexica-example-question.png#bordered) + diff --git a/docs/use-cases/remote.reusables.md b/docs/use-cases/remote.reusables.md new file mode 100644 index 000000000..e5ed1722e --- /dev/null +++ b/docs/use-cases/remote.reusables.md @@ -0,0 +1,22 @@ +--- +search: false +--- + + + + + +:::info +iOS or macOS versions of LarePass will require adding a VPN configuration file to the system when turning on the VPN. Follow the prompts to complete the setup. +::: diff --git a/docs/use-cases/stable-diffusion.md b/docs/use-cases/stable-diffusion.md new file mode 100644 index 000000000..29f5823bb --- /dev/null +++ b/docs/use-cases/stable-diffusion.md @@ -0,0 +1,79 @@ +--- +description: Comprehensive guide to using Stable Diffusion in Olares. Learn about text-to-image generation, and how to optimize your SD Web UI deployment for multi-user environments. +--- +# Stable Diffusion +Stable Diffusion represents a groundbreaking implementation of latent diffusion models (LDMs) in AI image synthesis. This deep learning architecture operates by decomposing the image generation process into a lower-dimensional latent space, significantly reducing computational requirements while maintaining high-fidelity output. + +Olares simplifies the deployment and management of Stable Diffusion. Unlike traditional deployments that require manual configuration of file systems and databases, Olares shields developers from these infrastructure complexities, allowing you to focus solely on using the model for image generation. + +With Olares's multi-user support, team members can share a single Stable Diffusion deployment while maintaining individual data privacy. This approach eliminates the need for redundant system installations that would otherwise consume excessive hardware resources. +## What can Stable Diffusion do? +Whether you're an artist looking to expand your creative toolkit, a developer integrating AI imaging into your workflow, or simply curious about AI art generation, Stable Diffusion offers: + +* Text-to-image generation +* Image-to-image transformation +* Inpainting and outpainting capabilities +* Style transfer and artistic modifications +* High-resolution image creation and upscaling + +## Install SD Web UI + +:::info +Starting from Olares 1.11.6, if "SD Web UI For Cluster" or "SD Web UI" was previously installed, uninstall them before proceeding. +::: + +1. Install SD Web UI Shared directly from Market. + +2. Launch SD Web UI from your desktop. Please ensure the admin has already installed SD Web UI Shared. + +Now you are ready to unleash your creativity and start generating stunning images! + +## Prevent conflicts among members +In SD Web UI, checkpoint settings are globally applied to all users by default. When one user switches to a different checkpoint, all subsequent image generations by other users will also use this newly selected checkpoint. To prevent workflow disruptions in multi-user environments, you could specify checkpoints for individual tasks. + +![Checkpoint settings](/images/manual/use-cases/sd-checkpoint.png) +1. Global checkpoint +2. Per-task checkpoint + +## Adjust system settings +When launching SD Web UI, the `--xformers` flag is enabled by default to: +- Reduce VRAM usage +- Accelerate image generation +- Support higher resolution outputs + +While this optimization allows for higher resolution image generation, it comes with some trade-offs, such as less stylistic variation between generated images, and slightly reduced prompt interpretation accuracy. + +If you need to remove `--xformers`: + +:::info +Only Olares admin can adjust system parameters through the Control Hub app. +::: + +1. Open Control Hub, and navigate to **Browse**. +2. Locate **sdwebui** under the admin's namespace. +3. Under **Deployments**, click **sdwebui**. +4. Click more_vert in the top right corner, and click **Edit YAML**. +5. In the YAML editor, locate `--xformers` and remove it. The default YAML file should look similar to the following. + + ```yaml {5} + env: + - name: CLI_ARGS + value: >- + --allow-code --enable-insecure-extension-access --api + --no-hashing --gradio-queue --xformers + ``` + +6. Click **OK** to apply the system settings. + +## Gallery + + + + + + + + + + +
Image 1Image 2
Image 3Image 4
\ No newline at end of file diff --git a/docs/use-cases/stream-game.md b/docs/use-cases/stream-game.md new file mode 100644 index 000000000..f51275dc7 --- /dev/null +++ b/docs/use-cases/stream-game.md @@ -0,0 +1,153 @@ +--- +outline: [2, 3] +description: Comprehensive tutorial on streaming Steam games with Olares. Learn to install Steam Headless, configure the streaming service, and stream games on Moonlight from both local and remote networks. +--- + +# Stream your favorite games with Steam Headless + +Want to enjoy some gaming with the power of Olares? You are all set. With the Steam Headless app, Olares easily transforms into a steam streaming server. You can now play your favorite games on any compatible device via Moonlight or Steam Link. + +This guide walks you through installing Steam Headless on Olares, configuring the streaming service, and using the Moonlight client to stream your games. + + +## Objectives + +By the end of this tutorial, you will learn how to: + +- Install Steam Headless on Olares and configure compatibility for Windows games on the Steam client. +- Configure the streaming service, which involves pairing the Sunshine streaming server with the host on the Moonlight client. +- Stream games on the Moonlight client from both local and remote networks. + +## Before you begin + +Before you begin, ensure the following: + +- Olares is up and running on a machine equipped with an NVIDIA GPU. +- Your streaming device has Moonlight installed. Visit the [Moonlight website](https://moonlight-stream.org/) to download and install the appropriate version. +- [Enable LarePass VPN](../manual/larepass/private-network.md#enable-vpn-on-larepass) on your streaming device. +- You have a valid Steam account to access your games. + +## Install Steam Headless + +1. In Olares Market, find Steam Headless under the **Entertainment** category, and click **Get**. +2. Open Steam Headless, and then click **Connect** to access the Steam Headless console. +3. In the Steam Headless console, click the **Install** button to install and update the Steam client. Once completed, the Steam login page should appear. + ![Install Steam client](/images/manual/tutorials/install-steam-client.png#bordered) + +4. Log into your Steam account and complete the initial setup. + + ![Steam login interface](/images/manual/tutorials/steam-login.png#bordered) + +::: tip Retry installation upon failures +Due to network issues, Steam installation or update may fail. If this happens, go to the top-left menu in Steam console and navigate to **Applications** > **Internet** > **Steam** to reinstall. +::: + +## Configure game compatibility + +Olares runs on a Linux environment. You'll need to enable [Proton](https://github.com/ValveSoftware/Proton), a compatibility layer, to support Windows games. + +1. In the Steam client page, navigate to **Steam** > **Settings** in the top left corner. +2. Go to the **Compatibility** tab and check **Enable Steam Play for all other titles**. + ![Steam Settings](/images/manual/tutorials/steam-setting.png#bordered) +3. Restart the Steam client to view your complete game library. + +## Configure the streaming service + +Steam Headless also integrates Sunshine, the streaming server. To stream games using Moonlight, you need to pair the host PC on moonlight with Sunshine. + +### Prepare for paring + +1. From your Steam client in the browser, get the URL and append `:47990`, for example, `https://139ebc4f0..olares.com:47990`. Open this URL to access the Sunshine console page. + + ![Sunshine console page](/images/manual/tutorials/access-sunshine.png#bordered) + +2. On your first visit, log in using the default credentials: + - Username: `sam` + - Password: `password` + +3. Click the **Pin** tab to open the pairing page, where you will be prompted to enter the pairing code. + + ![Sunshine's paring page](/images/manual/tutorials/pin-sunshine.png#bordered) + + +### Add host in Moonlight + +1. Open the Moonlight client on your streaming device and click the add_to_queue button in the top-right corner. + +2. When promoted to enter the IP address of your host PC, enter the URL of Steam, for example, `139ebc4f0..olares.com`. + + ::: tip Note + Do not include `https://`. + ::: + +3. Click **OK**, and a host icon appears in locked status. +4. Click the host icon to receive a pairing code. + + ![Get pin code](/images/manual/tutorials/get-pin-code.png#bordered) + +### Complete paring + +1. In Sunshine's paring page, enter the pairing code. +2. Enter a name for the device and click **Send** to finish pairing. If successful, you will see the message: "Success! Please check Moonlight to continue". +3. Check the host status in Moonlight. The icon should be active now. + ![Paring successfully](/images/manual/tutorials/active-host-moonlight.png#bordered) + +## Stream your game + +Now you are done with configuring and ready for gaming. + +### Stream locally + +If you are streaming locally from the same network of Olares: + +1. Open Moonlight on your streaming device. +2. Click your steam host, and then click the Steam icon to enter the Steam Big Screen mode and play. + + ![Stream game](/images/manual/tutorials/stream-success.png#bordered) + +### Stream remotely + +With Olares's VPN feature, you can enjoy a smooth streaming experience even across different networks. + +To enable the VPN: + + + +Once VPN is enabled on your device, simply follow the same instructions as local streaming. + +## FAQs + +### Why isn't the game displaying in full screen? + +This could be due to your resolution settings. Try adjusting the resolution: +- In Moonlight: adjust in **Settings** > **Basic Settings** > **Resolution and FPS**. +- On the Steam console page: adjust in **Applications** > **Settings** > **Display**. + + ![Set display](/images/manual/tutorials/set-steam-display.png#bordered) + +### How do I exit full-screen streaming? + +To exit streaming in the full-screen mode: +- **On Windows**: Use the shortcut combo **Ctrl + Alt + Shift + Q**. +- **On Mac**: Use the shortcut combo **Control (^) + Option (⌥) + Shift + Q**. +- **On mobile devices**: use the controller button combo **Start + Select + L1 + R1**. + +After finishing your streaming session, exit the Steam Big Picture mode to release system resources on Olares. + +### Where are my downloaded games stored? + +By default, games are stored at: + +`/Cache/olares/steam-headless/c0/.steam/debian-installation/steamapps/common` + +We recommend not changing this default directory. + + + + + + + + + + diff --git a/docs/use-cases/stream-media.md b/docs/use-cases/stream-media.md new file mode 100644 index 000000000..368f631ba --- /dev/null +++ b/docs/use-cases/stream-media.md @@ -0,0 +1,66 @@ +--- +outline: [2, 3] +description: Comprehensive tutorial on streaming media with Olares. Learn to configure VPN access, manage media files through LarePass, and set up Jellyfin for advanced streaming capabilities from anywhere. +--- + +# Stream your media library from anywhere with Olares +Olares makes it easy to access and enjoy your personal media library from anywhere, whether you're at home or on the go. With built-in VPN support and media management tools like Jellyfin, you can stream your favorite movies and TV shows securely and seamlessly. This tutorial will guide you through the process of setting up Olares VPN, accessing media files, and configuring Jellyfin for advanced streaming capabilities. + +## Objectives +In this tutorial, you will learn how to: +- Configure Olares VPN to securely access your media library from anywhere with LAN-like performance. +- Explore and play video files stored in Olares Files using the LarePass client or a web browser. +- Install and set up Jellyfin for media streaming. + +## Enable Olares VPN connection +To achieve smooth streaming across networks, [enable VPN connection](../manual/larepass/private-network.md) in LarePass for your streaming device. Devices with activated VPN will use the VPN connection to access Olares, whether through the LarePass client or a browser. +:::tip +For different LarePass download options, visit [the official page](https://olares.com/larepass). +::: + + + +## Access media files in LarePass +After enabling VPN, you can browse media files stored on Olares. + +### Access via LarePass Client +1. Open LarePass, and navigate to your media directory containing movies and TV shows in Files. +2. Click on any file to start playback on your computer or mobile device. + +### Access from browser +1. Open files from your Olares desktop, or directly using the app's URL: `https://files.[OlaresDomainName]`. +2. Locate your media directory, and click on video files to begin playback. + +## Access media files using Jellyfin +For advanced media management features like subtitle support and multi-channel audio, install Jellyfin. + +1. Open the Market app in Olares and go to the **Entertainment** category. +2. Locate and download Jellyfin. +3. Launch Jellyfin and complete first-time setup: + - Set administrator password. + - Configure media library directories. +4. Wait for Jellyfin to scan and index your media library. It will automatically fetch metadata including: + - Movie posters + - Descriptions + - Cast information + +![Jellyfin](/images/manual/use-cases/jellyfin.png#bordered) +## Access your media library through Jellyfin clients +To stream your media on various devices: + +1. Configure Jellyfin authentication. + + a. Open Settings, and navigate to **Applications** > **Jellyfin** > **Entrances**. + + b. Set **Authentication level** to **Internal**. +2. Download and install [Jellyfin's official client](https://jellyfin.org/downloads/). +3. Connect clients to your Jellyfin server in Olares. + + a. In your Jellyfin client, auto-discovery should locate your server for devices on the same network. + + b. If auto-discovery fails, manually enter the server address from Olares. + +4. Log in to Jellyfin client with your credentials. +:::tip +Keep the VPN connection active for optimal streaming performance when accessing your media library remotely. +::: diff --git a/docs/use-cases/wise.reusables.md b/docs/use-cases/wise.reusables.md new file mode 100644 index 000000000..7244c9c26 --- /dev/null +++ b/docs/use-cases/wise.reusables.md @@ -0,0 +1,32 @@ +--- +search: false +--- +将你的内容收集到 Wise 后，你可以通过 Olares 的聚合搜索功能进行全文搜索。 + +![搜索 Wise](/images/zh/manual/tutorials/wise-search.png#bordered) + +::: info 搜索格式 +目前仅支持文档类型内容（PDF、网页文章和 EPUB）的搜索。其他格式将在后续版本中支持。 +::: + +1. 点击 Dock 中的 search 打开搜索窗口。 +2. 指定搜索范围为 Wise，并输入关键词进行搜索。 + +:::info +具体步骤可能会因操作系统和浏览器而有所不同。以下以 Safari 为例。 +::: + +1. 在浏览器中点击 ios_share，选择 LarePass 为分享对象。你可以： + - 在分享选项中选择 LarePass 的图标，或者 + - 在**其他操作**栏中选择 **LarePass** + + ![收藏到 Wise](/images/zh/manual/tutorials/wise-add-articles-via-share.png#bordered) + + LarePass 应用会自动打开并检测待分享页面的内容，并提示是否要添加至 Wise。 +2. 点击**确认**添加。 + +::: tip 复制 URL 分享 +你也可以直接复制网页 URL 并打开 LarePass。LarePass 会自动检测剪贴板中的 URL 和可收藏的内容。 +::: + +收集完成后，可以在 Wise 的**库** > **文章**中阅读收集的文章。 \ No newline at end of file diff --git a/docs/vercel.json b/docs/vercel.json new file mode 100644 index 000000000..f351ca578 --- /dev/null +++ b/docs/vercel.json @@ -0,0 +1,21 @@ +{ + "headers": [ + { + "source": "/assets/(.*)", + "headers": [ + { + "key": "Cache-Control", + "value": "max-age=31536000, immutable" + } + ] + } + ], + + "redirects": [ + { + "source": "/", + "destination": "/manual/docs-home.html", + "permanent": true + } + ] +} diff --git a/docs/zh/developer/contribute/olares-id/contract/architecture.md b/docs/zh/developer/contribute/olares-id/contract/architecture.md new file mode 100644 index 000000000..2931c2eed --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/architecture.md @@ -0,0 +1,119 @@ +--- +outline: [2, 4] +--- + +# TerminusDID 合约系统 + +## 架构 + +TerminusDID 合约系统分为两个部分：DID 管理和标签管理。除了标签管理的核心功能外，我们还实现了一个官方 Tagger 和一个信誉系统。 + +```mermaid +graph TB + + RootTagger{RootTagger} + + RSAPubKey[/RSAPubKey/] + DNSARecord[/DNSARecord/] + AuthAddress[/AuthAddress/] + otherTag[/.../] + + + + + TerminusDID{TerminusDID} + Reputations[/Reputations\] + XXXReputation{...} + AppMarketReputation{AppMarketReputation} + Tag[[Tag]] + Tagger([Tagger]) + + + DID[DID] + Domain((Domain)) + com((com)) + net((net)) + io((io)) + + TerminusDID--->DID + TerminusDID--->Tag + Tag--->Tagger + + Tagger-.-RootTagger + Tagger-.-AppMarketReputation + Tagger-.-XXXReputation + + + Domain-.->Tag + + + subgraph ide4 [Tag] + + subgraph ide1 [OfficialTag] + RootTagger--->RSAPubKey + RootTagger--->DNSARecord + RootTagger--->AuthAddress + RootTagger--->otherTag + end + + subgraph ide2 [Reputations] + Reputations-.->AppMarketReputation + Reputations-.->XXXReputation + end + + end + + subgraph ide3 [DID] + DID-.-Domain + Domain--->com + Domain--->net + Domain--->io + end + +```` + +关于 DID/标签管理的用法，请参考[此处](https://www.google.com/search?q=./contract.md)；关于 TerminusDID 合约的设计细节，请参考[此处](https://www.google.com/search?q=././did/design.md)；关于信誉系统的推荐实现和示例，请参考[此处](https://www.google.com/search?q=./contract-reputation.md)。 + +## 设计细节 + +### Multicall + +考虑到我们合约使用场景的复杂性和不确定性，我们添加了一个内置的 multicall 函数来简化链上交互。你可以在单笔交易中访问多个接口，而无需外部辅助合约。 + +### EIP-7201 + +我们遵循 EIP-7201 进行合约数据存储，这使得合约升级更轻松、更安全，也有利于实现对数据的精细化控制。 + +### Olare ID 的验证 + +在注册时，Olare ID 是以 `string` 类型提交的。尽管它通过 `.` 来进行层级分离，但这无法保证其正确性和可读性。我们在合约代码中实现了额外的验证，以确保提交的名称是经过 UTF-8 编码的可读字符串。 + +### 标签中结构体的字段名 + +为了提高 Gas 效率，如果标签类型中包含结构体，其字段名将通过以太坊事件 (Ethereum events) 发布在链上，而不占用合约存储。事件将记录定义该标签类型时的区块高度。使用区块高度、合约地址、事件签名和布隆过滤器 (Bloom filters)，可以精确地获取所需事件。 + +### 内联汇编 (Inline Assembly) + +我们使用基于内联汇编的切片类型来解析和遍历 Olares ID 的层级，这可以避免复制子字符串并降低 Gas 消耗。 + +## 附录 - 需求 + +### DID + +- 链上 [DID](https://www.w3.org/TR/did-core/) 管理（偏好于 EVM 兼容链） +- 为 DID 记录 IPv4/IPv6、头像、RSA 公钥等信息 +- 为未来可能出现的新需求扩展存储数据 + +### Olares ID + +- 为 Olares ID 区分两种 DID：组织 (Organization) 或个人 (Individual) +- 为父级组织派生 DID 管理权限 + +### 信誉 (Reputation) + +- 使用另一种称为“实体 (Entity)”的 DID 来代表现实世界中的对象（例如，用于应用市场信誉的应用版本和用于 Otmoic 信誉的投诉） + +:::tip 提示 +我们希望基于 DID 合约设计一个去中心化的信用体系。起初，我们设想的是一个能适应各种场景的通用系统，但随着逐步实现，我们发现这个庞大而全面的系统会带来许多不必要的资源消耗，并降低在不同场景下的灵活性。因此我们改变了方向：我们提供一个用于抽象和必要组件的信誉 (Reputation) 系统，并提供一些推荐实现。用户可以组合和定制实现，以满足自己的场景需求。 +::: + diff --git a/docs/zh/developer/contribute/olares-id/contract/contract-reputation.md b/docs/zh/developer/contribute/olares-id/contract/contract-reputation.md new file mode 100644 index 000000000..1c0a1eb5b --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/contract-reputation.md @@ -0,0 +1,96 @@ +# 声誉 (Reputation) + +#### 额外需求：抽象的声誉系统 + +:::info 所需功能 + +- **映射到现实世界对象的标识符** + 所有信用系统都基于一些特定场景，例如对应用的评价或对商家的投诉。这不可避免地需要我们为一些现实世界或抽象的对象建立唯一的链上标识符。 + +- **身份验证** + 信用系统最核心的功能是评价，而评价者的身份验证是其先决条件之一。 + +- **必要信息的存储** + 用户评价后，我们可能需要记录评论或计算一些加权统计数据。 + +- **历史记录与更新** + 在某些情况下，我们可能需要记录评价行为，并允许将来更新现有评价。 +::: + +本章为每个需求提供了相应的解决方案。 + +## 待评价的对象 + +对于待评价的对象，可能会出现以下两种情况： + +- **是一个商家或单一个人** + 在这种情况下，该对象必须拥有一个“个人 (Individual)”类型的 DID，这样我们就可以直接操作该对象，而无需创建其他 DID。 +- **是一个现实世界的对象或抽象概念** + 在这种情况下，我们首先需要为此对象创建一个“实体 (Entity)”类型的 DID，然后对其进行操作。 + +## 身份验证 + +身份验证有两种解决方案： + +- 使用 DID 的所有者 (owner) 提交交易 (tx)，并让 Tagger 调用 Olares DID 合约的接口进行身份验证。 +- 使用 DID 的所有者签署一个自定义的 EIP-712 消息，并使用一个转发器 (forwarder) 将交易发送上链。Tagger 将使用消息的签名者进行身份验证。 + +:::tip 提示 +我们推荐第二种方案，因为交易费用由转发器支付，而不是评价者。 +::: + +## 必要信息的存储 + +对于“实体 (Entity)”类型的 DID，我们定义该 DID 自身的标签，并将必要的数据写入其中。对于“个人 (Individual)”类型的 DID，我们将该场景抽象为一个“实体 (Entity)”类型的 DID，并向其标签中写入数据。 + +## 历史记录与更新 + +我们可以遵循上一节的建议，将数据存储在实体的标签中。但在某些场景中并不需要链上查询，此时链上存储就是一种浪费。对于这些情况，我们建议使用以太坊事件 (Ethereum events)进行记录，并在 Tagger 中自定义具体实现。 + +## 示例 - OtmoicReputation + +:::info + +```mermaid + flowchart LR + + otmoic{{OtmoicReputation}} + did{{TerminusDID}} + complaints[/tag-complaints/] + otmoicdid((otmoic.reputation)) + + otmoic-- Authentication -->did + did-.->otmoicdid + otmoicdid-.-complaints + otmoic-- read/write -->complaints +```` + +Otmoic Reputation 合约使用 DID 所有者的 EIP-712 签名进行身份验证，并将被投诉的出价 `bidid` 存储在实体 `otmoic.reputation` 的 `complaints` 标签中。 +::: + +## 示例 - TerminusAppMarketReputation + +:::info +```mermaid + flowchart TD + + app((app.myterminus.com)) + appname((appname.app.myterminus.com)) + version1((version1.appname.app.myterminus.com)) + version2((version2.appname.app.myterminus.com)) + reputation{{TerminusAppMarketReputation}} + ratings[/tag-ratings/] + version1ratings[/version1-tag-ratings/] + event[[event]] + + app-->appname + appname-->version1 + appname-->version2 + app-.->ratings + ratings-.-version1ratings + version1-.-version1ratings + reputation-.- read/write -.->version1ratings + reputation-.->event +``` +Olares App Market Reputation 合约同样使用 DID 所有者的 EIP-712 签名进行身份验证。合约的评分数据存储在实体 `..app.myterminus.com` 的 `ratings` 标签中，而评论数据则以以太坊事件的形式发布，而不是存储在链上。 +::: diff --git a/docs/zh/developer/contribute/olares-id/contract/contract.md b/docs/zh/developer/contribute/olares-id/contract/contract.md new file mode 100644 index 000000000..dc8b13b84 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/contract.md @@ -0,0 +1,208 @@ +# 智能合约 + +Olares ID 的智能合约包含两个部分。 + +- [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol) 合约扮演着关键角色，并作为 [DID Registry (DID 注册表)](https://www.google.com/search?q=/manual/concepts/registry.md)。查看[合约](https://optimistic.etherscan.io/address/0x5da4fa8e567d86e52ef8da860de1be8f54cae97d)。 +- 第三方协议可以基于 [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol) 扩展信誉系统。目前，已部署以下信誉协议： + - [Otmoic Trader Reputation](https://github.com/otmoic/reputation-contract-evm/blob/main/contracts/Reputation.sol)。查看[合约](https://optimistic.etherscan.io/address/0xE924F7f68D1dcd004720e107F62c6303aF271ed3)。 + - [Application Reputation](https://github.com/beclab/terminusdid-contract-system/blob/main/src/taggers/TerminusAppMarketReputation.sol)。查看[合约](https://optimistic.etherscan.io/address/0x08065353D266121938B93D4B1071Bb52CD0C0EE4)。 + +# TerminusDID + +TerminusDID 合约管理着一个源自 [Domain (域)](https://docs.jointerminus.com/overview/terminus/terminus-name.html#domain) 的层级结构。 + +## 节点 (Node) + +每个节点都拥有几个默认属性。 + +| 属性 | 描述 | +| ---------------- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| name | 指定[域名 (Domain Name)](/zh/manual/concepts/olares-id#域名类型)。某些域名可与 Olares ID 互换。 | +| id | 每个节点也是一个遵循 **ERC-721** 标准的 NFT。其 id 是该 NFT 的唯一标识符，通过 `keccak256(name)` 计算得出。 | +| did,owner | 节点的 `owner` 和 `did`，由相同的助记词派生而来。更多详情请见[此处](https://www.google.com/search?q=/manual/concepts/did.md)。\此外，存储 owner 的好处在于它遵循 **BIP44** 规范，有助于在 EVM 合约内进行节省 Gas 的签名验证。每个节点都隶属于一个 `owner`，该 `owner` 有权修改节点详情。 | +| note | 目前有三种类型：个人 (Individual)、组织 (Organization) 和实体 (Entity)。 | +| allowSubdomain | 指示其是否为叶子节点。如果为 False，该节点无法派生更多子节点。 | + +以下是一个指定节点默认属性的示例： + +```json +{ + "id": "0xbf90de759829bfa3d2b10e4c4a7101e3b116f70b9a5431951ff9d83a4c8e3ceb", + "name": "olivia.myterminus.com", + "did": "did:key:z6MkuhT5kYegHaJxirMaHxuqzJhGZk5r32Ct5nYVRQWpN31q", + "note": "Individual", + "owner": "0x1404C95b2Cb2E46E03650bc02f83364A92f8DA9D", + "allowSubdomain": true +} +``` + +## 所有者 (Owner) + +不同节点的所有权如下： + +- **系统 (System)**\ + 诸如 `root`、`com`、`io` 等抽象节点属于 Terminus 团队。 + +- **个人 (Individual)** \ + `myterminus.com` 属于[个人域 (Individual Domain)](/zh/manual/concepts/olares-id.md#域名类型)，由 Terminus 团队所有。 + `alice.myterminus.com` 和 `bob.myterminus.com` 属于个人 Terminus 名称，由各自的用户所有。 + +- **组织 (Organization)** \ + `org1.com` 和 `org.io` 属于[组织域 (Organization Domain)](/zh/manual/concepts/olares-id.md#域名类型)，由域管理员所有。 + `alice.org1.com` 和 `bob.org2.io` 属于组织 Terminus 名称，由各自的用户所有。 + +- **实体 (Entity)** \ + `Application Score` 属于[实体域 (Entity Domain)](/zh/manual/concepts/olares-id.md#域名类型)，由该实体的申请人所有。组织管理员和用户可以参考[域管理](https://www.google.com/search?q=../contract/manage/contract.md%23register-did)来管理他们自己的节点和子节点。 + +:::info +项目稳定后，Terminus 团队会将所有权转移给 DAO 组织的多签地址。 +::: + +## 标签 (Tag) + +[Tag (标签)](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TagRegistry.sol) 机制允许 [TerminusDID](https://github.com/beclab/terminusdid-contract-system/blob/main/src/core/TerminusDID.sol) 合约扩展节点上存储的元数据。 + +例如，如果你是一家管理组织域的企业，并希望为组织下的每位员工添加 `employee-id` (员工ID) 属性，你就需要基于标签进行扩展。 + +标签系统允许你以特定的编码格式 (ABI) 在链上自由存储 `uint`、`int`、`address`、`boolean`、`bytes`、`string`、`structure`、`fixed length array`、`variable length array` 等数据类型。在读写数据之前，你需要定义数据类型。你定义的数据类型将适用于其自身及其所有子节点。**定义者 (definer)、使用者 (user) 和标签名 (Tag name)** 的信息用于索引一条唯一的数据。 + +:::info 注意 + +对于复杂结构或数组，以及复杂结构和数组相互嵌套的情况，如果每次都以标签为单位写入数据，将会导致巨大的无效 Gas 消耗。因此，我们在系统中实现了单独更新单个字段或操作单个数组的功能。在执行单次更新时，除了**定义者、使用者和标签名**之外，你还需要提供数据的**路径 (path)**，即结构体内部的变量名。 +::: + +### 自定义标签 + +| 字段 | 描述 | +| ------------ | -------------------------------------------------------------------------- | +| name | 此标签的名称 | +| did | 定义此标签的 DID | +| abiType | 此标签的数据类型，遵循 **abi** 的编码规范，也支持定义复杂结构 | +| fieldNames | 定义复杂结构时，内部子结构或数据的名称在一个二维数组中被扁平化 | + +:::tip 注意 +作为自定义标签的 Owner/did 仅对该节点及其子节点有效。 +::: + +### Tagger + +Tagger 是每个标签内部的必要信息之一。它代表有权修改标签值的唯一实体，可以是一个钱包地址或一个合约。Tagger 可能会频繁更改。 + +::: tip Note +我们建议你使用合约作为 Tagger。 + +- 参考几个官方 Tagger 的实现，你可以利用 DID 合约进行全面的操作者身份验证，同时实现更精细的自定义权限控制。 +- 对于复杂的标签结构或具有特殊规范的数据内容，将 Tagger 设置为合约可以在链上验证数据格式或建立更全面的自定义规则。例如，对于官方标签中 RSAPubKey 的值，我们在链上对 Pkcs8 ASN.1 格式的字节数据进行验证，以防止设置无法解析的值。 +::: + +## 使用案例 + +在根 (Root) 节点下提供了一些 Tagger： + +- RSAPubKey: 用户可以声明 RSA 公钥，第三方可以基于此公钥向他们发送私密消息。 +- AuthAddresses: 用户可以声明他们拥有的钱包地址。 +- DNSARecord: 用户可以声明边缘节点的 DNS A 记录。 + +:::info 关于 AuthAddresses +以下系统依赖于此标签的数据操作： + +- **设置头像** + + 在系统中设置头像时，你可以选择你拥有的任何 NFT 图片作为头像。判断你是否拥有某个 NFT 的标准是其所有者的地址是否存在于 AuthAddresses 中。 + +- **Otmoic lp** + + Otmoic lp 以 TerminusName 作为账户进行操作。在签署交易信息时，它会验证签名者的地址是否存在于 AuthAddresses 中。 + +因为 AuthAddresses 涉及另一个钱包，仅验证交易的发送者是不可信的。因此，我们设计了以下操作方案： + +使用声明的地址和 DID 所有者，遵循 EIP712 标准签署以下信息，并在限定时间内（签署后30分钟内）提交给合约进行验证。 + +```json +{ + "address": "0x10FE2771907B0c4245695daD7e9Ed064d45860f8", + "algorithm": 0, // 0: ECDSA + "domain": "olivia.myterminus.com", + "signAt": "1714287578", + "action": 0 // 0: Add 1: Remove +} +``` + +::: + +# 信誉 (Reputation) + +我们可以基于 Tagger 创建高度灵活的[信誉](https://www.google.com/search?q=/manual/concepts/reputation.md)协议。 + +在实现链上信誉系统时，最关键的要素是： + +- 抽象和表示待评估的对象 +- 评估对象并存储必要信息 +- 验证评估者的身份 + +针对这些要素，TerminusDID 提供了一套全面的解决方案。我们可以使用个人 (Individual) 和实体 (Entity) 类型的 DID 来代表待评估的对象，使用标签 (Tags) 来存储扩展的元数据，并利用 TerminusDID 内置的权限管理功能来验证身份。在以下两个案例中了解更多信息。 + +## Otmoic Trader Reputation + +Otmoic 的信誉合约使用 DID 所有者的 EIP712 签名进行身份验证，然后将投诉的 DID (complain did) 存储在 `otmoic.reputation` 实体的 `complaints` 字段中。 + +:::info 部署 + +1. 在 TerminusDID 合约中创建实体 `otmoic.reputation`。 +2. 定义一个名为 `complaints` 的标签。 +3. 部署 Otmoic Trader Reputation [合约](https://optimistic.etherscan.io/address/0xE924F7f68D1dcd004720e107F62c6303aF271ed3)。 +4. 将 `complaints` 的 Tagger 设置为 Otmoic Trader Reputation。 + ::: + +:::info 用法 + +1. 使用 DID 所有者遵循 EIP712 签署交易信息。 +2. 将交易信息和签名提交给 Otmoic Trader Reputation。 + ::: + +:::info 结构 +```mermaid + flowchart LR + + otmoic{{OtmoicReputation}} + did{{TerminusDID}} + complaints[/tag-complaints/] + otmoicdid((otmoic.reputation)) + + otmoic-- Authentication -->did + did-.->otmoicdid + otmoicdid-.-complaints + otmoic-- read/write -->complaints +``` +::: + +## 应用声誉 + +1. 定义名为 `ratings` 的标签，并将其 Tagger 设置为 Application Reputation 合约。 +2. 当应用有新版本时，在区块链上创建 **`..app.myterminus.com`**。 +3. 用户签署评论/评分信息，并提交给 Application Reputation 合约。 +4. Application Reputation 合约将评分信息保存到 `..app.myterminus.com` 的 Ratings 中，并以事件 (event) 的形式发布评论信息。 + +:::info +```mermaid + flowchart TD + + app((app.myterminus.com)) + appname((appname.app.myterminus.com)) + version1((version1.appname.app.myterminus.com)) + version2((version2.appname.app.myterminus.com)) + reputation{{TerminusAppMarketReputation}} + ratings[/tag-ratings/] + version1ratings[/version1-tag-ratings/] + event[[event]] + + app-->appname + appname-->version1 + appname-->version2 + app-.->ratings + ratings-.-version1ratings + version1-.-version1ratings + reputation-.- read/write -.->version1ratings + reputation-.->event +``` +::: \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares-id/contract/did/design.md b/docs/zh/developer/contribute/olares-id/contract/did/design.md new file mode 100644 index 000000000..059c371f1 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/did/design.md @@ -0,0 +1,279 @@ +--- +outline: [2, 3] +--- + +# DID + +## DID 的设计 + +### DID 中包含的数据 + +#### id + +每个 DID 同时也是一个 NFT（遵循 **ERC-721** 标准），`id` 是通过 `keccak256(name)` 计算得出的其唯一标识符。 + +#### did + +由助记词派生而来，用于依赖 DID 的系统中的身份验证。 + +#### owner + +同样由助记词派生（遵循 **BIP-44** 标准），用于身份验证（主要是在链上合约中）。 + +#### note + +DID 目前有以下几种类型： + +- 个人 (Individual) +- 组织 (Organization) +- 实体 (Entity) + +:::info TName 的命名规则 +一个有效的 TName 标签，即由 `.` 分隔的每个部分： + +- 是格式良好且非空的 UTF-8 序列；且 +- 仅包含 Unicode 编码类别为 L, M, N, P, S 的码点；且 +- 不包含以下范围内的 Unicode 码点： + - 句号 (Full Stop) (U+002E) + - 蒙古文自由变体选择符 (Mongolian Free Variation Selectors) (U+180B..U+180D) + - 变体选择符 (Variation Selectors) (U+FE00..U+FE0F) + - 替换字符 (Replacement Characters) (U+FFFC..U+FFFD) + - 变体选择符补充 (Variation Selectors Supplement) (U+E0100..U+E01EF)。 +- 大小写敏感，例如 `MAX.com` 和 `max.com` 是不同的 TName。 +- 支持包括中文在内的多种字符，例如 `博物馆.中国` + 参考: [https://www.compart.com/en/unicode/category](https://www.compart.com/en/unicode/category) + ::: + +### 标签系统 (Tag System) + +除了基础数据，我们希望在 DID 中维护一些状态或信息。这就是我们实现标签系统的原因。 + +#### 如何使用 + +1. 定义一个标签 +2. 向标签写入数据 + +:::tip 注意 +标签的定义和结构很复杂。如果你感兴趣，请参阅合约的技术细节。 +这里我们简要介绍一个标签定义中包含的信息。 + + - name: 此标签的名称 + - did: 定义此标签的 DID + - abiType: 此标签的数据类型，遵循 Solidity ABI 规范并支持复杂结构 +- fieldNames: 此标签内部结构体的字段名，使用前序遍历扁平化为二维字符串数组 +::: + +#### 标签的作用域 + +每个标签仅适用于定义它的 DID 及其子域。 +例如，如果标签 `employeeId` 是在 DID `a-certain-company.com` 中定义的，其子域 `james.a-certain-company.com` 可以为自己设置 `employeeId` 的值为 `"001"`。如果某个 DID 既没有定义该标签，也不是定义者（definer）的子域，例如 `another-company.com` 和 `emma.another-company.com`，则无法设置该标签的值。 + +```mermaid + graph TB + + a-certain((a-certain-company.com)) + another-company((another-company.com)) + emma((emma.another-company.com)) + james((james.a-certain-company.com)) + olivia((olivia.a-certain-company.com)) + employee-id[/employee-id/] + + a-certain-->james + a-certain-->olivia + another-company-->emma + a-certain-.-employee-id + employee-id-.->james + employee-id-.->olivia +``` + +#### Tagger + +Tagger 是每个标签中的必要信息之一。与固定的定义不同，Tagger 可以被更改。 +Tagger 代表唯一有权修改该标签值的个人或程序。它可以是一个钱包地址或一个智能合约。 + +::: tip Note +我们建议你使用智能合约作为 Tagger。 + + - 你可以利用 Olares DID 合约进行完整的操作者身份验证，同时实现更细粒度的自定义访问控制。请参考一些官方的 Tagger 实现。 + - 对于复杂的标签结构或具有特殊格式的数据，使用合约 Tagger 支持在链上验证数据格式并自定义规则。例如，在官方 Tagger 中，我们将在链上验证 PKCS8 ASN.1 格式的字节数据，以防止意外为 `RSAPubKey` 标签设置无法解析的值。 +::: + +### 由谁创建 DID + +考虑到并非每个人都有足够的 Gas 用于链上操作，并且愿意使用现有 DID 的 owner 地址，我们提供了由官方 forwarder (转发器) 为你代发交易的选项。当然，如果你愿意，也可以自己操作。 + +### DID 的权限 + +一个 DID 对其自身及其所有子域拥有管理权限。对于直接注册的三级域名，例如 `a.b.c`（在 `b.c` 未注册的情况下），`b.c` 的 owner 将被设置为 `0x0...00d1d`，并由官方管理。 + +### 流程与概念介绍 + +TName 的扩展信息由 Olares DID 合约的标签系统管理。每个标签不仅有名称，还有标签类型。目前支持的类型包括 `int`, `uint`, `bool`, `string`, `address`, `bytes`, `bytesN`, `array`, `arrayN` 和 `tuple`。元组 (tuple) 支持额外的字段名。 +由于标签与 TName 绑定，设置标签的步骤如下： + +- 在一个 TName 中定义一个标签，包括标签名、标签类型以及元组中的字段名。设置字段名并非易事，详情请参阅文档 "DIDv2.3Tag 类型注册流程介绍"。 + +代码示例 + +```solidity +function defineTag( + string calldata domain, + string calldata name, + bytes calldata abiType, + string[][] calldata fieldNames +) public +``` + +- 设置负责写入此标签的 Tagger。Tagger 可以是 EOA 或合约地址。复杂的验证逻辑可以在合约 Tagger 中实现。 + +代码示例: + +```solidity +function setTagger(string calldata domain, string calldata name, address tagger) public +``` + +- 接下来，你可以在该标签的定义者及其子域上对此标签执行 CRUD 操作。 + +```solidity +function addTag(string calldata from, string calldata to, string calldata name, bytes calldata value) public +function removeTag(string calldata from, string calldata to, string calldata name) public +function getTagElem(string calldata from, string calldata to, string calldata name, uint256[] calldata elemPath) + public + view +returns (bytes memory) +function updateTagElem( + string calldata from, + string calldata to, + string calldata name, + uint256[] calldata elemPath, + bytes calldata value +) public +function getTagElemLength( + string calldata from, + string calldata to, + string calldata name, + uint256[] calldata elemPath +) public view returns (uint256) +function pushTagElem( + string calldata from, + string calldata to, + string calldata name, + uint256[] calldata elemPath, + bytes calldata value +) public +function popTagElem(string calldata from, string calldata to, string calldata name, uint256[] calldata elemPath) public +``` + +其中： + +- `from` 是定义此标签的 TName +- `to` 是要设置此标签的 TName +- `name` 是标签名 +- `value` 是经过 `abi.encode` 后的字节值 +- `elemPath` 用于 `array` 和 `tuple` 类型，以访问单个元素。对于其他类型，只需设置为空数组。其值被视为多维数组的索引（也可以将 `tuple` 视为数组）。例如，以下 `Student` 类型有4层嵌套的元组，我们可以设置 `elemPath` 为 `[1,2,1,0,0]` 来读取或更新 `Student s -> Class class -> Teacher[1] teachers -> People info -> string name`。请注意，虽然我们只有4层嵌套的元组，但 `elemPath` 的长度为5，因为 `teachers` 是一个数组，增加了一个嵌套层级。 + +```solidity +struct Student { + People info; + Class class; +} + +struct Class { + uint8 grade; + uint8 classNum; + Teacher[] teachers; +} + +struct People { + string name; + uint8 age; + string gender; +} + +struct Teacher { + People info; + string subject; +} +Student s; +``` + +- Olares DID 合约提供了一组特殊的标签，称为官方标签。它在空 TName `""` 中定义，其 Tagger 被指定为 `RootTagger`。所有 TName 都可以设置官方标签，我们稍后将介绍详细的访问控制策略。 + +### 标签的访问控制 + +1. 在 TName 中定义标签，即设置标签名和类型 + + - 官方标签：`operator` (运营方) 拥有权限 + - 其他标签：此 TName 的 owner (所有者) 拥有权限 + 在以下情况下，定义标签可能会失败： + - 一个标签名在同一个 TName 中只能定义一次，不能重复 + - 标签名和元组的字段名必须以 [a-z] 开头，且只包含 [a-zA-Z0-9] + - 标签类型的字节表示长度不能超过 31 + - 标签类型必须遵循 `ABI` 库中的类型约束 + - `fieldNames` 的值必须与定义中的元组类型匹配 + - 一个元组不能有重复的字段名 + +2. 设置 Tagger： + + - 官方标签：`operator` 拥有权限 + - 其他标签：此 TName 的 owner 拥有权限 + +3. 设置标签： + + Tagger 负责设置标签时的访问控制。接下来我们介绍官方标签的情况。 + +## 注册规则与访问控制 + +从合约的角度来看，目前只有 operator 可以注册顶级 TName。普通注册通过调用 `register` 接口完成，参数包括 TName 的 owner 和一些元数据。元数据在注册后是不可变的。子 TName 可以由 operator 或其任一父 TName 的 owner 注册。 +也就是说，只有以下角色可以执行注册： + +- 合约的 `operator` +- 父 TName 的 owner 可以注册一个子 TName + 在以下情况下，注册可能会失败： + - 当 TName 不是顶级域名时：父 TName 尚未注册，或父 TName 的元数据指定其不能拥有子 TName + - TName 包含无效的标签 + - TName 已被注册 + - TName 的 owner 被指定为零地址 + +**代码示例**： + +```solidity +struct Metadata { +string domain; +string did; +string notes; +bool allowSubdomain; +} + +function register(address tokenOwner, Metadata calldata metadata) public returns (uint256 tokenId) +``` + +注册后，合约将铸造一个 ERC-721 NFT，并返回一个 token ID (`tokenId`)。它是 TName 字符串的 Keccak-256 哈希值。 + +**代码示例**： + +```solidity +function tokenId(string memory domain) internal pure returns (uint256) { +return uint256(keccak256(bytes(domain))); +} +``` + +由于该 NFT 与 ERC721 兼容，它支持标准的 ERC-721 操作，如 `transferFrom` 和 `approve`。因此，所有权可以由以下地址转移： + +- TName 的 owner +- owner 的委托人 +- 经 owner 批准的地址 + +Terminus DID 合约额外增加了两个拥有转移权限的地址： + +- 合约的 `operator` +- 父 TName 的 owner + +## 合约的角色 +Olares DID 合约有一个 owner 用于升级自身。它还有一个超级用户，即 `operator`，以方便进行配置。每个 TName 都有其自己的 owner。 + +合约 owner 的权限包括： + +- 设置 operator 地址 +- 转移合约的所有权 +- 升级合约 \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares-id/contract/did/faq.md b/docs/zh/developer/contribute/olares-id/contract/did/faq.md new file mode 100644 index 000000000..04eea3ed0 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/did/faq.md @@ -0,0 +1,11 @@ +# 常见问题 (FAQ) + +## 交易费用 + +当你申请 Olares ID 时，我们可以为你支付调用合约的交易费用。流程大致如下： + +- 你向我们提供由你的私钥签名的数据和签名 +- 我们将交易发送至智能合约 +- 区块链在验证签名后会记录你的数据 + +之后如果你需要管理你名下的数据，则应通过 MetaMask 调用合约。或者，你也可以使用 LarePass 登录 Olares Space，并自行支付交易费用。 \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares-id/contract/did/official-taggers.md b/docs/zh/developer/contribute/olares-id/contract/did/official-taggers.md new file mode 100644 index 000000000..2cb72f6b5 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/did/official-taggers.md @@ -0,0 +1,23 @@ +# 官方 Tagger + +## RootTagger + +目前我们定义了以下标签，并使用 `RootTagger` 作为它们的 Tagger： + +- **rsaPubKey**: TName 的 RSA 公钥 + - 类型: `bytes` + - 访问权限: operator、TName 的 owner (所有者)，以及父 TName 的 owner。 +- **dnsARecord**: TName 的 IP 地址 + - 类型: `bytes4` + - 访问权限: operator、TName 的 owner，以及父 TName 的 owner。 +- **latestDID**: TName 最新的 DID (添加此标签是因为元数据是不可变的) + - 类型: `string` + - 访问权限: operator、TName 的 owner，以及父 TName 的 owner。 +- **authAddresses**: 由 TName 的 owner 控制的地址 + - 类型: `tuple(uint8,address)[]` + - 访问权限: 任何持有 TName 的 owner 和被添加地址的 EIP-712 签名的人。 + +## AppStoreReputation + +此外还有一个特殊的 Tagger `AppStoreReputation`，用于在 TName `app.myterminus.com` 中定义的 `ratings` 标签，其类型为 `tuple(string,uint8)[]`。它为 Terminus OS 中应用的评分提供链上存储。每个应用都有一个对应的子 TName `..app.myterminus.com`，任何拥有 TName 的人都可以为这些应用提交评分。 +``` \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares-id/contract/did/release-history.md b/docs/zh/developer/contribute/olares-id/contract/did/release-history.md new file mode 100644 index 000000000..a2de6e04e --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/did/release-history.md @@ -0,0 +1,21 @@ +# 发布历史 + +## V2.0.0 + +在 Terminus DID 中实现 DID 模块的核心架构。 + +## V2.1.0 + +添加无定义的标签系统。 + +## V2.2.0 + +升级标签系统以包含类型定义。 + +## V2.3.0 + +优化合约结构并减小核心合约大小。 + +## V2.3.1 + +修复 Bug：当 EIP-712 签名恢复失败时，进行 Revert 操作，而不是使用零地址继续执行。 \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares-id/contract/manage/contract.md b/docs/zh/developer/contribute/olares-id/contract/manage/contract.md new file mode 100644 index 000000000..12592738f --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/manage/contract.md @@ -0,0 +1,104 @@ +--- +outline: [2, 3] +--- + +# 直接调用合约 + +## DID + +### 获取元数据 (metadata) + +获取 DID 的元数据有两个接口 - `getMetadata(tokenId)` 和 `getMetadata(name)`。 + +#### 返回值 + +```json +[ + "james.myterminus.com", // 名称 (name) + "did:key:z6MkpLwxcTwhj4MRm4eKhvBadK45qHr5QEYHUXNyhCfkXJ9U#z6MkpLwxcTwhj4MRm4eKhvBadK45qHr5QEYHUXNyhCfkXJ9U", // 从助记词派生的 DID + "OrganizationalUser", // DID 类型 + true // 是否允许创建子域？ +] +```` + +### 获取域的所有者 + +调用 `ownerOf(tokenId)` 来获取 DID 的链上控制者地址。 + +### 按创建索引获取 token + +调用 `tokenByIndex(index)` 来获取指定索引的 token。它返回一个 **token ID**。 + +### 按所有者和索引获取 token + +尽管从业务角度我们不允许单个钱包拥有多个 DID，但考虑到未来可能的所有权转移和 NFT 交易，合约本身是允许的。在这种情况下，可以调用 `tokenOfOwnerByIndex(owner, index)` 来获取指定地址拥有的、具有指定索引的 token。它返回一个 **token ID**。 + +### 注册 DID + +域的所有者可以调用 `register(owner, MetaData(domain, did, note, allowSubdomain))` 来注册其子域。 + +> [\!NOTE] +> 第一个参数 **owner** 是新 DID 的指定所有者，第二个参数是一个元数据结构体，包含： +> +> - domain: 新 DID 的完整域名，同时也是一个 Terminus Name +> - did: 从所有者钱包派生的 DID +> - note: 关于新 DID 的备注，供链下系统用于分类 +> - allowSubdomain: 是否允许新 DID 注册子域 +> +> 元数据在注册后不可更改。如果将来所有权发生转移，新的 DID 记录将被写入 `latestDid` 标签中。 + +## 标签 (Tag) + +### 获取由某个名称定义的标签数量 + +`getDefinedTagCount(name)` 返回由指定 TName 定义的标签数量。 + +### 获取标签名 + +与上述接口配合使用，`getDefinedTagNameByIndex(name, index)` 返回单个标签名，而 `getDefinedTagNames(name)` 返回由指定 TName 定义的所有标签名。 + +### 结构化标签 + +如果一个标签类型是复杂结构而不是原始值，调用 `getTagType(name, tagName)` 来查询结构定义，然后使用先前返回的 **fieldNamesHash** 调用 `getFieldNamesEventBlock(fieldNamesHash)` 来获取定义此标签时的区块号。最后，使用 `ethers` 库来获取定义中的字段名。 + +> [\!NOTE] +> 查询标签类型的接口返回一个 ABI 类型的编码字节，应根据代码表进行解析。查询字段名可能很复杂且容易出错，因此我们建议使用 SDK 中的函数来获取关于标签的数据，而不是手动调用合约。 + +获取标签类型后，调用 `getTagElem(definedDidName, valueDidName, tagName, elemPath)` 来获取标签的值。 + +> [\!NOTE] +> +> - definedDidName: 定义此标签的 TName +> - valueDidName: 你想获取其标签值的 TName +> - elemPath: 路径选择器，用于读取元组或数组中的内部元素（`[]` 用于读取完整标签） +> +> 此接口返回 ABI 编码的数据，应根据标签类型进行解析。 +> 同样建议使用 SDK 而不是手动调用合约。 + +### 定义标签 + +使用 `didName` 的所有者调用 `defineTag(didName, tagName, abiType, fieldNames)` 来定义一个标签。 + +> [\!NOTE] +> +> - abiType: 此标签的数据类型，遵循我们的 **ABI** 代码格式，支持复杂结构 +> - fieldNames: 此标签内部结构体的字段名，使用前序遍历扁平化为二维字符串数组 + +### CRUD (增删改查) + +> [\!NOTE] +> 我们建议与 Tagger 合约交互，而不是使用以下接口来执行标签操作。 + +- **创建 (Create)** - 调用 `addTag(defineDidName, valueDidName, tagName, value)` 来添加一个标签。 + +- **更新 (Update)** - 调用 `updateTagElem(defineDidName, valueDidName, tagName, elemPath, value)` 来更新标签中的一部分数据。 + +- **删除 (Delete)** - 调用 `removeTag(defineDidName, valueDidName, tagName)` 来删除一个标签。这会删除在某个 DID 上设置的标签，而不是删除标签定义本身。 + +- **数组操作 (Array operations)** - 如果标签类型包含数组，调用 `popTagElem(defineDidName, valueDidName, tagName, elePaths)` 和 `pushTagElem(defineDidName, valueDidName, tagName, elePaths, value)` 来执行数组特有的操作。 + +> [\!NOTE] +> +> - defineDidName: 定义此标签的 TName +> - valueDidName: 在其上设置标签值的 TName +> - value: ABI 编码的标签值 diff --git a/docs/zh/developer/contribute/olares-id/contract/manage/environment.md b/docs/zh/developer/contribute/olares-id/contract/manage/environment.md new file mode 100644 index 000000000..b746a74ac --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/manage/environment.md @@ -0,0 +1,23 @@ +--- +outline: [2, 3] +--- + +# 环境 + +## Sepolia Optimistic + +- TerminusDID: 0x4c8c98e652d6a01494971a8faF5d3b68338f9ED4 +- RootTagger: 0xaA5bE49799b6A71Eda74d22D01F7A808aFf41b3f +- LibABI: 0xdc9e8faDe38eE9E2Eb43761f1553CD2360ecAEac + +## Optimistic + +- TerminusDID: 0x5da4fa8e567d86e52ef8da860de1be8f54cae97d +- RootTagger: 0xe2eaba0979277a90511f8873ae1e8ca26b54e740 +- LibABI: 0x9ae3f16bd99294af1784beb1a0a5c84bf2636365 + +> [!NOTE] +> RootTagger 是以下官方标签的 Tagger： - DNSARecord - RSAPubKey - LatestDid - AuthAddress + +> [!NOTE] +> LibABI 是一个独立的库合约，提供 ABI 类型编码、数据转换等功能。 diff --git a/docs/zh/developer/contribute/olares-id/contract/manage/sdk.md b/docs/zh/developer/contribute/olares-id/contract/manage/sdk.md new file mode 100644 index 000000000..c6a37a563 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/contract/manage/sdk.md @@ -0,0 +1,299 @@ +--- +outline: [2, 3] +--- + +# 使用 SDK 进行管理 + +## DID + +### 获取所有 DID + +有时出于统计或其他原因，我们需要完整的数据。以下 `fetchAll` 方法利用合约接口来获取完整数据。虽然它直接从链上接口获取结果，而不是遍历以太坊事件，但由于数据量大，这可能会非常耗时。 + +```Typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const dids = await did.fetchAll() + + console.log('dids:', dids) + + console.log('format dids:', await did.formatDatas(dids)) +} + +fetch() +```` + +> [\!NOTE] +> 如果在开发环境中运行且日志记录已开启，执行期间会显示获取进度。 + +#### 快速获取 + +为方便起见，SDK 提供了 `formatDatas` 和 `loadDatas` 两个函数。`formatDatas` 返回的数据可以被存储，下次通过 `loadDatas` 加载以减少同步时间。一个更简单的方法是访问官方 **did-support** 服务中的 `/all` 端点，其返回的数据也可以被 `loadDatas` 加载。 + +### 查询特定 DID + +阅读了上述合约接口后，你应该会注意到合约并未提供单个接口来获取与某个 DID 相关的完整数据。因此，我们简化了 SDK 中的接口设计，其中 `fetchDomain` 会返回一个 DID 的完整数据。 + +```typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + console.log('did:', domain) +} + +fetch() +``` + +#### 快速查询 + +在你执行了上述 SDK 示例中的 `loadDatas` 后，`fetchDomain` 会首先尝试匹配本地数据，仅当本地机器上没有此 DID 的数据时，才会从链上获取。 + +#### 更新 DID + +如果你担心快速查询返回的不是最新数据，可以使用 `updateDomain` 或 `updateDomainById` 来更新本地数据。 + +#### 模糊匹配 + +与快速查询类似，在本地加载数据后，你可以使用 SDK 中的模糊匹配功能。以下两个函数仅匹配本地数据： + +```typescript +import DID from 'did-contract-developer-components' +//... code + +// 按 owner 查询 DID 并返回所有子域 +const domainsByOwner = DID.Domain.findSubtreesByOwner(owner, did.treesCache) + +// 按 did 查询 DID 并返回所有子域 +const domainsByDid = DID.Domain.findSubtreesByDid(did, did.treesCache) + +``` + +## 标签 (Tag) + +### 获取某个 DID 的所有标签 + +与直接调用合约不同，此函数返回的数据中包含了已解析的标签结构和结构体字段名。 + +```typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + const tags = await DID.Domain.fetchAllTagType(domain, did.getContractDID()) + + console.log('tags:', tags) +} + +fetch() +``` + +### 获取某个 DID 的所有标签值 + +与上述方法类似，此函数返回带有 JSON 格式标签值的已解析数据。 + +```typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const fetch = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + await DID.Domain.fetchAllTagType(domain, did.getContractDID()) + + const tags = await DID.Domain.fetchAllTagValue(domain, did.getContractDID()) + + console.dir(tags, {depth: null}); +} + +fetch() +``` + +### 定义标签 + +使用 SDK 定义标签时，你可以使用面向对象的方法构建标签类型的内部结构，而无需担心编码问题。以下示例包含了大多数常见的数据类型。 + +```typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const defineTag = async () => { + + // 标签名: simpleTagBox + const tagName = 'simpleTagBox' + + // tuple + const testTuple = new DID.Tag.TagValueTypeTuple(undefined, undefined, true); + + // uint + const testUint = new DID.Tag.TagValueTypeUint(undefined, undefined, true); + testUint.setSize(8) + + // address + const testAddress = new DID.Tag.TagValueTypeAddress(undefined, undefined, true); + + // array
+ const testArrayAddress = new DID.Tag.TagValueTypeArray(undefined, undefined, true); + testArrayAddress.setBuliderType(testAddress) + + // bool + const testBool= new DID.Tag.TagValueTypeBool(undefined, undefined, true) + + // bytes + const testBytes = new DID.Tag.TagValueTypeBytes(undefined, undefined, true) + + // int + const testInt = new DID.Tag.TagValueTypeInt(undefined, undefined, true) + testInt.setSize(256) + + // flarray + const testFlarrayInt = new DID.Tag.TagValueTypeFlarray(undefined, undefined, true) + testFlarrayInt.setBuliderType(testInt) + testFlarrayInt.setSize(3) + + // flbytes + const testFlbytes = new DID.Tag.TagValueTypeFlbytes(undefined, undefined, true) + testFlbytes.setSize(5) + + // string + const testString = new DID.Tag.TagValueTypeString(undefined, undefined, true) + + testTuple.setField('testUint', testUint) + testTuple.setField('testArrayAddress', testArrayAddress) + testTuple.setField('testBool', testBool) + testTuple.setField('testBytes', testBytes) + testTuple.setField('testFlarrayInt', testFlarrayInt) + testTuple.setField('testFlbytes', testFlbytes) + testTuple.setField('testString', testString) + + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + await DID.Domain.defineTag(domain, tagName, testTuple, did.getContractDIDByPrivateKey('you-private-key'), did) +} + +defineTag() +``` + +### 设置 Tagger + +```typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const setTagger = async () => { + + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + const [tag] = domain.tags.filter(tag => tag.name == 'simpleTagBox') + + DID.Domain.setTagger(tag, 'you-tagger-address', did.getContractDIDByPrivateKey('you-private-key')) +} + +setTagger() +``` + +### 设置标签值 + +与上面定义标签类似，当使用 SDK 设置标签值时，你只需传入合适的 JSON 数据，无需担心编码问题。以下示例中的标签类型与上面定义标签部分中的相同。 + +```typescript +import DID from 'did-contract-developer-components' + +const RPC = "you-rpc-url" +const CONTRACT_DID = "0x5da4fa8e567d86e52ef8da860de1be8f54cae97d" +const CONTRACT_ROOT_RESOLVER = "0xe2eaba0979277a90511f8873ae1e8ca26b54e740" +const CONTRACT_ABI_TYPE = "0x9ae3f16bd99294af1784beb1a0a5c84bf2636365" + +const setTagValue = async () => { + const did = DID.createConsole(RPC, CONTRACT_DID, CONTRACT_ROOT_RESOLVER, CONTRACT_ABI_TYPE) + + const domain = await did.fetchDomain('james.myterminus.com') + + if (domain == undefined) { + throw new Error("not found"); + } + + console.log(domain) + const [tag] = domain.tags.filter(tag => tag.name == 'simpleTagBox') + const tagType = await DID.Domain.fetchTagStructure(tag, did.getContractDID()) + console.dir(tagType, {depth: null}) + + const ba1 = ethers.hexlify(Uint8Array.from([1, 2, 3])) + const ba2 = ethers.hexlify(Uint8Array.from([10, 18, 19])) + + const newData = { + testbox: { + testUint: 1, + testArrayAddress: ['0xF18B2Ea28c722CA87f951F5bF5327b66a7dd72A3', '0xecBA1d33b889f66ad426535f970d1E033ba5c79C'], + testBool: true, + testBytes: '0x0102030405' , + testFlarrayInt: [2, 3, 4], + testFlbytes: '0x0a0b0c0d0e', + testString: 'ok' + } + } + console.log('newData', newData) + + const call = await DID.Tag.doEncode(tagType, newData) + console.log('call', call) + + //设置 + const resp = await DID.Domain.setValue(tag, call, did.getContractDIDByPrivateKey('you-private-key')) +} + +setTagValue() +``` diff --git a/docs/zh/developer/contribute/olares-id/verifiable-credential/issuer.md b/docs/zh/developer/contribute/olares-id/verifiable-credential/issuer.md new file mode 100644 index 000000000..0f1b0c4ea --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/verifiable-credential/issuer.md @@ -0,0 +1,187 @@ +# 发行方 (Issuer) + +![alt text](/images/developer/contribute/issuer.png) + +以下是发行方的流程： + +1. 持有方 (Holder) 从发行方 (Issuer) 获取清单 (Manifest)。 +2. 持有方签名并提交申请 (Application)。 +3. 发行方自动或手动审查该申请。 +4. 持有方从发行方接收审查结果，如果获批则得到可验证凭证 (VC)，如果被拒则得到原因。 + +## 清单 (Manifest) + +此文件将返回给持有方。 +`outputDescriptors` 用于钱包展示可验证凭证 (VCs)。 +`presentationDefinition` 实际上是后续的 `manifest_presentation` 文件，用于确认用户提交的申请 (Application) 的格式。 + +```json +{ + "name": "Facebook Verifiable Credential Manifest", + "description": "Facebook Verifiable Credential Manifest", + "issuerDid": "", + "issuerName": "", + "outputDescriptors": [ + { + "id": "", + "schema": "", + "name": "Facebook Verifiable Credential Manifest", + "description": "Facebook Verifiable Credential Manifest", + "display": { + "title": { + "path": ["$.credentialSubject.name", "$.vc.credentialSubject.name"], + "schema": { "type": "string" } + }, + "subtitle": { + "path": ["$.credentialSubject.title", "$.vc.credentialSubject.title"], + "schema": { "type": "string" } + }, + "description": { + "path": [ + "$.credentialSubject.description", + "$.vc.credentialSubject.description" + ], + "schema": { "type": "string" } + }, + "properties": [ + { + "path": ["$.credentialSubject.id", "$.vc.credentialSubject.id"], + "schema": { "type": "string" }, + "label": "ID" + }, + { + "path": [ + "$.credentialSubject.email", + "$.vc.credentialSubject.email" + ], + "schema": { "type": "string" }, + "label": "Email" + } + ] + }, + "styles": { + "background": { + "color": "#FFFFFF" + }, + "text": { + "color": "#000000" + } + } + } + ], + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "presentationDefinition": {} +} +```` + +## 清单呈现 (Manifest Presentation) + +发行方使用此文件来验证持有方提交的申请 (Application) 的格式。 + +```json +{ + "name": "Facebook Manifest Presentation Definition", + "purpose": "Provide your token required to Facebook", + "inputDescriptors": [ + { + "id": "token", + "name": "Access Token", + "purpose": "Provide your token required to Facebook", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.token"] + } + ], + "subject_is_issuer": "preferred" + } + } + ], + "author": "" +} +``` + +## 申请可验证凭证 (Application Verifiable Credential) + +虽然用户在客户端仅需 `manifest_presentation` 来构建 VC 数据，但服务器需要一个 schema 来验证 `manifest_presentation` 是否符合格式要求。 +此文件将返回给持有方，以便持有方了解需要提交以供验证的数据格式。 +在 Facebook、Twitter 和 Gmail 的场景中，用户在客户端登录并获取访问令牌 (access token)，然后将其提交给发行方服务器，发行方服务器可以凭此访问令牌从 Facebook 等服务器获取用户的基本信息。因此用户只需提交简单的 token 即可。 +但在 KYC（了解你的客户）场景中，用户需要提交全名、身份证照片甚至验证视频等，此文件中的字段会变得复杂得多。 + +```json +{ + "author": "", + "name": "Facebook Verifiable Credential Request Schema", + "schema": { + "$id": "facebook-schema-1.0", + "$schema": "[https://json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)", + "description": "Facebook Verifiable Credential Schema", + "type": "object", + "properties": { + "token": { + "type": "string" + } + }, + "required": ["token"], + "additionalProperties": true + }, + "sign": false +} +``` + +## 可验证凭证 (Verifiable Credential) + +发行方返回给持有方的 VC 格式。 + +```json +{ + "author": "", + "name": "Facebook Verifiable Credential Schema", + "schema": { + "$id": "facebook-schema-1.0", + "$schema": "[https://json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema)", + "description": "Facebook Verifiable Credential Schema", + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "title": { + "type": "string" + }, + "description": { + "type": "string" + }, + + "facebook_name": { + "type": "string" + }, + "profile_image": { + "type": "string" + }, + "email": { + "type": "string" + }, + "facebook_id": { + "type": "string" + }, + "picture_is_silhouette": { + "type": "boolean" + } + }, + "required": ["name", "title", "description", "facebook_name"], + "additionalProperties": true + }, + "sign": false +} +``` + diff --git a/docs/zh/developer/contribute/olares-id/verifiable-credential/olares.md b/docs/zh/developer/contribute/olares-id/verifiable-credential/olares.md new file mode 100644 index 000000000..7efa0a780 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/verifiable-credential/olares.md @@ -0,0 +1,46 @@ +# Olares 的案例 + +虽然 DID 解决了去中心化网络中的身份问题，但它们通常难以记忆，不便在日常情况下使用。Olares ID 提供了一种类似于电子邮件地址的、易于记忆的熟悉格式，同时仍然利用了 DID 的强大功能和安全性。每个 Olares ID 都与一个 DID 绑定。 + +## 潜在的公平性问题 + +Olares ID 注册中的**先到先得**系统可能会带来一些公平性问题，例如： + +1. **欺诈：** 例如，Olares ID `elonmusk@myterminus.com` 可能会被并非埃隆·马斯克本人注册。 +2. **投机：** 抢注热门名称可能会导致投机行为，这虽然可能促进早期网络活跃度，但会牺牲公平性。 + +## Olares ID 的 VC 流程 + +为了解决潜在的公平性问题，我们采纳了 Web5 团队提出的**自主身份 (Self-Sovereign Identity, SSI)** 服务原则，并结合了 Olares ID 的 [VC 流程](/zh/manual/concepts/vc.md#六步验证流程)。这引导我们设计了一个**发行方 (Issuer) 和验证方 (Verifier)** 流程，以协助用户申请 **Olares ID**。 + +![alt text](/images/developer/contribute/vc-process.jpeg) + +### Gmail 发行方服务 + +我们利用谷歌的 OAuth 流程来促进**可验证凭证 (Verifiable Credentials, VCs)** 的发行。简化流程如下： + +1. Alice 在钱包客户端 LarePass 中通过 OAuth 登录她的 Gmail 账户。 +2. 谷歌将 OAuth 凭证返回给 LarePass。 +3. LarePass 将 OAuth 凭证提交给发行方。 +4. 发行方与谷歌服务器确认凭证的有效性，并检索基本信息（例如，电子邮件名称）。 +5. 发行方向 Alice 发行一个与其 Gmail 地址本地部分相匹配的 VC。 + +现在，Alice 就可以将已发行的 VC 存储在 LarePass 中。 + +:::tip 注意 +- 在整个过程中，Alice 仅向 LarePass 和发行方服务透露凭证授权范围内的基本账户数据，密码和隐私由谷歌的 OAuth 协议确保。 +- 所有用于设置 Gmail 发行方服务或其他 Web2 服务发行方服务的代码都在 GitHub 上开源。 + ::: + +### Olares ID 验证方服务 + +以下是 **验证方服务 (Verifier Service)** 在 Olares 端的运作方式： + +1. Alice 将她的 DID、Olares ID 和 Gmail VC 打包成一个**可验证表述 (Verifiable Presentation, VP)**，并将其与签名一同提交给验证方服务。 +2. 验证方服务会检查： + - 签名的有效性。 + - VP 中 VC 的有效性。 + - 该 Olares ID 是否可以在区块链上注册（如果使用多个渠道，如 Gmail 和 Twitter，获取 VC 信息，可能会产生冲突）。 +3. 所有检查通过后，验证方服务会将 Alice 的信息提交到区块链，并支付 Gas 费用。 + +至此，Alice 成功获得了她的 **Olares ID**。例如，如果你使用 Gmail 地址 “hello@gmail.com” 进行申请，所有检查完成后，你将获得 Olares ID “hello@olares.com”。 \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares-id/verifiable-credential/overview.md b/docs/zh/developer/contribute/olares-id/verifiable-credential/overview.md new file mode 100644 index 000000000..5ac008985 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/verifiable-credential/overview.md @@ -0,0 +1,55 @@ +# VC 服务 + +本文档旨在帮助你了解如何使用以下工具，为你自己的场景配置各种 schema 并创建发行方 (Issuers) 和验证方 (Verifiers)： +- Olares 的 [verifiable-credential-gate](https://github.com/Above-Os/verifiable-credential-gate) 和 [did-gate](https://github.com/Above-Os/did-gate) +- tbd 团队的 [SSI Service](https://github.com/TBD54566975/ssi-service) + +::: tip +如果你想进行更底层的开发，请结合 [SSI SDK](https://github.com/TBD54566975/ssi-sdk) 中的源代码阅读[协议标准](#reference)。 +::: + +## 简介 + +我们已经了解了 [VC](/zh/manual/concepts/vc.md) 的概念以及申请 VC 的基本流程。 + +在深入实现细节之前，我们可以先熟悉一下在钱包 (Wallet)、验证方 (Verifier) 和发行方 (Issuer) 的实际通信过程中会遇到的术语。 +| 术语 | 定义 | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **持有方 (Holder)** | 持有一个或多个可验证凭证的实体。持有方也是向验证方提交证明以满足其在“呈现定义 (Presentation Definition)”中描述的需求的实体。 | +| **发行方 (Issuer)** | 一个实体可以扮演的角色，通过对一个或多个主体断言声明，从这些声明中创建可验证凭证，并将其传输给持有方。 | +| **验证方 (Verifier)** | 定义了需要从持有方那里获取何种证明（通过“呈现定义”）以进行交互的实体。 | +| **可验证凭证 (VC)** | 一种防篡改的凭证，其所有权可以被加密验证。可验证凭证可用于构建可验证表述 (Verifiable Presentations)，该表述也可被加密验证。凭证中的声明可以关于不同的主体。PEX 接受三种形式的可验证凭证：1. JSON_LD，在我们的系统中称为 IVerifiableCredential；2. JWT 包装的 VC，在我们的系统中称为 JwtWrappedVerifiableCredential；或 3. 字符串，即一个有效的可验证凭证 jwt。 | +| **可验证表述 (VP)** | 一种防篡改的表述，其编码方式使得数据的所有权在经过加密验证后可以被信任。 | +| **清单 (Manifest)** | 凭证清单 (Credential Manifests) 用于描述哪些凭证可供发行。 | +| **申请 (Application)** | 持有方提供给发行方的格式。 | +| **呈现定义 (Presentation Definition)** | 阐明验证方需要何种证明的对象。 | +| **呈现 (Presentation)** | 源自一个或多个发行方所发行的一个或多个可验证凭证的数据。 | +| **提交 (Submission)** | TBC (待补充) | +| **定义 (Definition)** | TBC (待补充) | +| **Schema** | 所有不同的清单、申请、凭证、呈现、定义都需要使用 JSON 来定义 Schema。服务将验证所提交数据的正确性，然后进入业务流程。 | + +## 参考资料 + +以下参考资料来自 [SSI SDK](https://github.com/TBD54566975/ssi-sdk) 项目。 + +### 规范 + +以下是本库目前支持的一系列规范参考。这是一个动态集合，会随着库的演进而变化。 + +- [去中心化标识符 (DIDs) v1.0](https://www.w3.org/TR/did-core/) W3C 建议提案 2021年8月3日 +- [可验证凭证数据模型 v1.1](https://www.w3.org/TR/vc-data-model/) W3C 推荐标准 2021年11月9日 + - 支持 [链接数据证明 (Linked Data Proof)](https://www.w3.org/TR/vc-data-model/#data-integrity-proofs) 格式。 + - 支持 [VC-JWT 和 VP-JWT](https://www.w3.org/TR/vc-data-model/#json-web-token) 格式。 +- [可验证凭证 JSON Schema 规范](https://w3c-ccg.github.io/vc-json-schemas/v2/index.html) 社区组报告草案 2021年9月21日 +- [呈现交换 (Presentation Exchange) 2.0.0](https://identity.foundation/presentation-exchange/) 工作组草案 2022年3月 +- [钱包渲染草案 (Wallet Rendering Strawman)](https://identity.foundation/wallet-rendering/) 2022年6月 +- [凭证清单 (Credential Manifest)](https://identity.foundation/credential-manifest/) 草案 2022年6月 +- [状态列表 (Status List) 2021](https://w3c-ccg.github.io/vc-status-list-2021/) 社区组报告草案 2022年4月4日 + +### 签名方法 + +> - [数据完整性 (Data Integrity) 1.0](https://w3c.github.io/vc-data-integrity/) 社区组报告草案 +> - [链接数据加密套件注册表 (Linked Data Cryptographic Suite Registry)](https://w3c-ccg.github.io/ld-cryptosuite-registry/) 社区组报告草案 2020年12月29日 +> - [JSON Web 签名 (JSON Web Signature) 2020](https://w3c-ccg.github.io/lds-jws2020/) 社区组报告草案 2022年2月9日 +> - [VC 证明格式测试套件，使用 JSON Web 签名的 VC 数据模型](https://identity.foundation/JWS-Test-Suite/) 非官方草案 2022年3月9日 本实现对 JWS 测试套件的合规性可以在此处找到。 +> - 支持 JWT 和链接数据证明两种格式，并符合 [JOSE 规范](https://jose.readthedocs.io/en/latest/)。 \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares-id/verifiable-credential/verifer.md b/docs/zh/developer/contribute/olares-id/verifiable-credential/verifer.md new file mode 100644 index 000000000..9c3911539 --- /dev/null +++ b/docs/zh/developer/contribute/olares-id/verifiable-credential/verifer.md @@ -0,0 +1,164 @@ +# 验证方服务 (Verifier Service) + +关于此流程，请参考[呈现交换 (Presentation Exchange)](https://identity.foundation/presentation-exchange/) +![verifier](/images/developer/contribute/verifier.png)。 + +## 呈现定义 (Presentation Definition) + +1. 验证方 (Verifier) 将此文件返回给持有方 (Holder)。 +2. 持有方根据规范填写内容后，将符合格式要求的打包文件提交给验证方。 + +```json +{ + "name": "Facebook Basic Info Presentation Definition", + "purpose": "Provide your facebook basic info", + "inputDescriptors": [ + { + "id": "name", + "name": "Name", + "purpose": "Provide vc name", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.name"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "title", + "name": "Title", + "purpose": "Provide vc title", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.title"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "description", + "name": "description", + "purpose": "Provide vc description", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.description"] + } + ], + "subject_is_issuer": "preferred" + } + }, + + { + "id": "facebook_name", + "name": "Provide your facebook name", + "purpose": "Provide your facebook name", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.facebook_name"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "profile_image", + "name": "Provide your facebook profile image", + "purpose": "Provide your facebook profile image", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.profile_image"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "email", + "name": "Provide your facebook email email info", + "purpose": "Provide your facebook email info", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.email"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "facebook_id", + "name": "Provide your facebook id", + "purpose": "Provide your facebook id", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.facebook_id"] + } + ], + "subject_is_issuer": "preferred" + } + }, + { + "id": "picture_is_silhouette", + "name": "Provide your facebook Picture is Silhouette", + "purpose": "Provide your facebook picture_is_silhouette", + "format": { + "jwt_vc": { + "alg": ["EdDSA"] + } + }, + "constraints": { + "fields": [ + { + "path": ["$.credentialSubject.picture_is_silhouette"] + } + ], + "subject_is_issuer": "preferred" + } + } + ], + "author": "" +} +``` \ No newline at end of file diff --git a/docs/zh/developer/contribute/olares.md b/docs/zh/developer/contribute/olares.md new file mode 100644 index 000000000..f98178dad --- /dev/null +++ b/docs/zh/developer/contribute/olares.md @@ -0,0 +1,92 @@ +# Olares + +## 目录结构 + +``` +olares +|-- apps # 系统应用 +| |-- agent +| |-- analytic +| |-- market +| |-- market-server +| |-- argo +| |-- desktop +| |-- devbox +| |-- vault +| |-- files +| |-- knowledge +| |-- nitro +| |-- notifications +| |-- profile +| |-- rss +| |-- search +| |-- settings +| |-- system-apps +| |-- wise +| |-- wizard +|-- build # Olares installer +| |-- installer +| |-- manifest +|-- frameworks # 系统运行时组件 +| |-- app-service +| |-- backup-server +| |-- bfl +| |-- GPU +| |-- l4-bfl-proxy +| |-- osnode-init +| |-- system-server +| |-- tapr +|-- libs # 工具包库 +| |-- fs-lib +|-- scripts # 用于构建或打包 olares 安装程序的脚本 +|-- third-party # Olares 中集成的第三方库或应用程序 +| |-- authelia +| |-- headscale +| |-- infisical +| |-- juicefs +| |-- ks-console +| |-- ks-installer +| |-- kube-state-metrics +| |-- notification-mananger +| |-- predixy +| |-- redis-cluster-operator +| |-- seafile-server +| |-- seahub +| |-- tailscale +``` + +## 如何安装 + +``` +curl -fsSL https://olares.sh | bash - +``` + +## 如何构建 + +``` +git clone https://github.com/beclab/olares + +cd olares + +bash scripts/build.sh + +``` + +运行以上脚本，你将获得 debug 版本安装包 `install-wizard-debug.tar.gz`。 + +## How to install debug version + +``` +mkdir -p /path/to/unpack && cd /path/to/unpack + +tar zxvf /path/to/olares/install-wizard-debug.tar.gz + +make install VERSION=0.0.0-DEBUG + +``` + +## 如何卸载 + +```bash +olares-cli uninstall --all +``` diff --git a/docs/zh/developer/contribute/overview.md b/docs/zh/developer/contribute/overview.md new file mode 100644 index 000000000..59eb3a573 --- /dev/null +++ b/docs/zh/developer/contribute/overview.md @@ -0,0 +1,7 @@ +# Contributing To Olares + +## Olares + +## TermiPass + +## Develop System App diff --git a/docs/zh/developer/contribute/system-app/deployment.md b/docs/zh/developer/contribute/system-app/deployment.md new file mode 100644 index 000000000..34fa3b2ae --- /dev/null +++ b/docs/zh/developer/contribute/system-app/deployment.md @@ -0,0 +1,293 @@ +--- +outline: [2, 3] +--- + +# deployment.md + +由于系统应用需要安装到 `user-space` 的 namespace 下，所以需要做一些特殊修改。 + +1. 修改 chart 包中的 `deployment.yaml` 文件。 +2. 先将原有的 deployment 和 service 对应的 namespace 改为 `user-space-{\{ .Values.bfl.username }}`。 + ```Yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: desktop-dev + namespace: user-space-{{ .Values.bfl.username }} + ``` + +3. 参照 Olares 中的应用对应 `deployment.yaml` 文件配置，添加 `annotation` 和 `label`。 + + ```Yaml + metadata: + name: desktop-dev + namespace: user-space-{{ .Values.bfl.username }} + labels: + app: desktop-dev + applications.app.bytetrade.io/name: desktop-dev + applications.app.bytetrade.io/owner: {{ .Values.bfl.username }} + applications.app.bytetrade.io/author: bytetrade.io + annotations: + applications.app.bytetrade.io/icon: https://docs-dev.olares.com/icon.png + applications.app.bytetrade.io/title: Desktop-dev + applications.app.bytetrade.io/version: '0.0.1' + + # 此处的 entrances 配置要与 OlaresManifest.yaml 中配置保持一致 + applications.app.bytetrade.io/entrances: '[{"name":"desktop-frontend-dev", "host":"desktop-svc-dev", "port":80,"title":"Desktop-dev"}]' + ``` + +4. 修改 service。 + + ```Yaml + --- + apiVersion: v1 + kind: Service + metadata: + name: desktop-svc-dev + namespace: user-space-{{ .Values.bfl.username }} + spec: + selector: + app: desktop-dev + ports: + - protocol: TCP + port: 80 + targetPort: 8080 # 注意，现在 nodejs 的 dev container 端口是 8080，要改成这个端口 + ``` + +5. 修改 `OlaresManifest.yaml` 中 `entrances` 的内容。 + + ```Yaml + entrances: + - name: desktop-frontend-dev # 与 deployment 上的 annotation 一致 + host: desktop-svc-dev # 与上面的 service 名字一致 + port: 80 + icon: https://file.bttcdn.com/appstore/default/defaulticon.webp + title: Desktop-dev + authLevel: private + openMethod: default + ``` + +6. 添加 service 提供 app-service 安装检查。 + + ```Yaml + # 提供 app-service 安装检查 + --- + apiVersion: v1 + kind: Service + metadata: + name: desktop-svc-dev # 必须与原来的 service 同名 + namespace: {{ .Release.Namespace }} + spec: + type: ExternalName + externalName: desktop-svc-dev.user-space-{{ .Values.bfl.username }}.svc.cluster.local + ports: + - protocol: TCP + name: desktop + port: 80 + targetPort: 80 + ``` + +7. 如果需要添加本地 cache 或者 juicefs 用户目录的访问，可添加： + + ```Yaml + volumes: + - name: appdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appData }}/desktop-dev + + - name: userdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.userData }}/desktop-dev + + - name: appcache + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appCache }}/desktop-dev + + ``` + +--- + +:::details 完整 `deployment.yaml` 文件例子 +```YAML +--- +apiVersion: apps/v1 +kind: Deployment +metadata: + name: desktop-dev + namespace: user-space-{{ .Values.bfl.username }} + labels: + app: desktop-dev + applications.app.bytetrade.io/name: desktop-dev + applications.app.bytetrade.io/owner: {{ .Values.bfl.username }} + applications.app.bytetrade.io/author: bytetrade.io + annotations: + applications.app.bytetrade.io/icon: https://docs-dev.jointerminus.com/icon.png + applications.app.bytetrade.io/title: Desktop-dev + applications.app.bytetrade.io/version: '0.0.1' + applications.app.bytetrade.io/entrances: '[{"name":"desktop-frontend-dev", "host":"desktop-svc-dev", "port":80,"title":"Desktop-dev"}]' +spec: + replicas: 1 + selector: + matchLabels: + app: desktop-dev + template: + metadata: + labels: + app: desktop-dev + spec: + volumes: + - name: terminus-sidecar-config + configMap: + name: sidecar-configs + items: + - key: envoy.yaml + path: envoy.yaml + - name: appdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appData }}/desktop-dev + + - name: userdata + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.userData }}/desktop-dev + + - name: appcache + hostPath: + type: DirectoryOrCreate + path: {{ .Values.userspace.appCache }}/desktop-dev + + initContainers: + - name: terminus-sidecar-init + image: openservicemesh/init:v1.2.3 + imagePullPolicy: IfNotPresent + securityContext: + privileged: true + capabilities: + add: + - NET_ADMIN + runAsNonRoot: false + runAsUser: 0 + command: + - /bin/sh + - -c + - | + iptables-restore --noflush <=0.1.0' + type: system + appScope: + clusterScoped: false + appRef: [] +``` +::: \ No newline at end of file diff --git a/docs/zh/developer/contribute/system-app/other.md b/docs/zh/developer/contribute/system-app/other.md new file mode 100644 index 000000000..c3970de7a --- /dev/null +++ b/docs/zh/developer/contribute/system-app/other.md @@ -0,0 +1,127 @@ +# 其它 + +## ProviderRegistry + +如果需要将原系统应用的 provider 接入你的开发环境可以手工修改 ProviderRegistry 的地址。在控制面板中的 **CRDs**，找到 `sys.bytetrade.io`，找到 `ProviderRegistry`。 + +![image](/images/developer/develop/contribute/system-app/other/provider_registry.jpg) + +进入列表后找到你要替换的应用（比如 desktop-notification），点击右侧的功能按钮，选择**编辑 YAML**. 将 yaml 中的` endpoint`，指向你的开发应用的 service 地址. 保存之后即可生效。 + +![image](/images/developer/develop/contribute/system-app/other/edit_yaml.jpg) + + +## vite 配置 + +如果前端项目采用了 vite，需要增加 hmr 配置。原因是 vite 在 dev 状态，会启动 websocket 监听服务器端发送的代码更新 reload 通知。默认 ws 端口为 server 启动的端口。而 dev app 启动了 nginx 代理，采用了标准的 443 端口。所以需要做相应修改。 + +如果是 quasar + vite，在 `quasar.config.js` 里增加一段 + +```js +extendViteConf(viteConf) { + viteConf.server.hmr = {clientPort: 443}; +}, +``` +如果是独立 vite 项目，需要修改 `vite.config.js` 文件。 +```js +export default defineConfig({ + server: { + hmr: { + clientPort: 443, + }, + }, +}); +``` + +## 使用系统数据库 + +在 `deployment.yaml` 中，添加 `MiddlewareRequest`。 +以 Dify 中申请 `postgres` 为例: +```Yaml +apiVersion: apr.bytetrade.io/v1alpha1 +kind: MiddlewareRequest +metadata: + name: dify-pg + namespace: os-system +spec: + app: dify + appNamespace: os-system + middleware: postgres + postgreSQL: + user: dify_os_system + password: + valueFrom: + secretKeyRef: + key: pg_password + name: dify-secrets + databases: + - name: dify +``` + +添加 Middleware request，需要设置一个密码的 secret。 + +```Yaml +apiVersion: v1 +kind: Secret +metadata: + name: dify-secrets + namespace: {{ .Release.Namespace }} +type: Opaque +data: + pg_password: {{ $pg_password }} # password 可以随机生成，然后做 Base64 encode +``` + +在使用的地方配置如下字段： + +```Yaml +env: + - name: DB_USERNAME + value: dify_user_space_{{ .Values.bfl.name }} # 注意，在上面配置的Middleware request配置的用户名，在实际使用时，需要加上namespace 后缀。Postgres的用户名，还需要把 - 换成 _ + - name: DB_PASSWORD + value: {{ $pg_password | b64dec }} # 上面配置的密码原文 + - name: DB_HOST + value: citus-master-svc.user-system-{{ .Values.bfl.username }} # 数据库地址， redis的地址为 redis-cluster-proxy.user-system-{{ .Values.bfl.username }}， mongo 地址为 mongo-cluster-mongos.user-system-{{ .Values.bfl.username }} + # Redis：redis-cluster-proxy.user-system-{{ .Values.bfl.username }} + # Mongo：mongo-cluster-mongos.user-system-{{ .Values.bfl.username }} + - name: DB_PORT + value: '5432' # redis 端口 6379，mongo 端口 27017 + # Redis：6379 + # Mongo：27017 + - name: DB_DATABASE + value: os_system_dify # 注意，在上面配置的 Middleware request 配置的数据库名，在实际使用时，需要加上 namespace 前缀。Postgres 的数据库名，还需要把 - 换成 _ +``` + +也可以拼接 `dsn` 链接： + +```Yaml +postgres://dify_{{ .Values.bfl.username }}:{{ $pg_password_data }}@citus-master-svc.user-system-{{ .Values.bfl.username }}/user_space_{{ .Values.bfl.username }}_dify?sslmode=disable + +mongodb://dify-{{ .Values.bfl.username }}:{{ $mongo_password_data }}@mongo-cluster-mongos.user-system-{{ .Values.bfl.username }}:27017/{{ .Release.Namespace }}_dify + +redis://:{{ $redis_password | b64dec }}@redis-cluster-proxy.user-system-{{ .Values.bfl.username }}:6379/0 # 注意，由于系统采用的是 redis cluster，db 只能写 0 +``` + +如果提供 provider 需要手工在 `deployment.yaml` 文件里配 `ProviderRegistry`。 + +```Yaml +apiVersion: sys.bytetrade.io/v1alpha1 +kind: ProviderRegistry +metadata: + name: desktop-provider-dev # 名字不能和现有的重名 + namespace: user-system-{{ .Values.bfl.username }} +spec: + + dataType: config-dev # 类型不要现在的重名，如果想替换现在的，需要把已有的删除 + deployment: desktop-dev + description: Set Desktop Config + endpoint: desktop-svc-dev.{{ .Release.Namespace }} # provider 的访问地址，指向开发的应用 + group: service.desktop + kind: provider + namespace: {{ .Release.Namespace }} + opApis: + - name: Update + uri: /server/updateDesktopConfig + version: v1 +status: + state: active +``` diff --git a/docs/zh/developer/contribute/system-app/overview.md b/docs/zh/developer/contribute/system-app/overview.md new file mode 100644 index 000000000..9cc1d2e16 --- /dev/null +++ b/docs/zh/developer/contribute/system-app/overview.md @@ -0,0 +1,19 @@ + +# 开发 Olares 的系统应用 + +::: tip 前置知识： +- 用 DevBox 调试第三方应用 +- 用 DevBox 开发程序 +- 了解 Olares 的架构和机制 + ::: + +经过一年半开发，Olares 团队在开发系统应用时已经逐渐迁移到 DevBox 上。 + +下面我们将演示如何在 Devbox 里调试 Desktop 的前端代码。 +1. 在 DevBox 中创建应用 +2. 配置 [deployment.yaml](./deployment) +3. 配置 [OlaresManifest.yaml](./olares-manifest) +4. 安装应用 +5. 配置 [nginx.conf](./install) + +还有[其它](./other)一些开发注意事项。 \ No newline at end of file diff --git a/docs/zh/developer/develop/advanced/account.md b/docs/zh/developer/develop/advanced/account.md new file mode 100644 index 000000000..349ff6bf6 --- /dev/null +++ b/docs/zh/developer/develop/advanced/account.md @@ -0,0 +1,80 @@ +# 账户 + +如果安装在 Olares 中的应用，需要同步系统的用户信息，以此作为应用中的用户，可以在应用 chart 中申明`SysEventRegistry`来获得系统中用户事件的回调。 + +- 用户创建回调申明 + + ```yaml + apiVersion: apr.bytetrade.io/v1alpha1 + kind: SysEventRegistry + metadata: + name: user-create-cb + namespace: "{{ .Release.Namespace }}" + spec: + type: subscriber + event: user.create + callback: http://app-svc.{{ .Release.Namespace }}:8080/callback/create + ``` + 系统回调 + ```http + POST /callback/create HTTP/1.1 + Content-Type: application/json + + { + "name": "user1", + "role": "workspace-manager", + "email": "user1@xxx.com" + } + ``` + +- 用户删除回调申明 + + ```yaml + apiVersion: apr.bytetrade.io/v1alpha1 + kind: SysEventRegistry + metadata: + name: user-delete-cb + namespace: "{{ .Release.Namespace }}" + spec: + type: subscriber + event: user.delete + callback: http://app-svc.{{ .Release.Namespace }}:8080/callback/delete + ``` + 系统回调 + ```http + POST /callback/delete HTTP/1.1 + Content-Type: application/json + + { + "name": "user1", + "email": "user1@xxx.com" + } + ``` + +- 用户激活事件回调 + + ```yaml + apiVersion: apr.bytetrade.io/v1alpha1 + kind: SysEventRegistry + metadata: + name: user-active-cb + namespace: "{{ .Release.Namespace }}" + spec: + type: subscriber + event: user.active + callback: http://app-svc.{{ .Release.Namespace }}:8080/callback/activate + ``` + 系统回调 + ```http + POST /callback/activate HTTP/1.1 + Content-Type: application/json + + { + "name": "user1", + "email": "user1@xxx.com" + } + ``` + +:::tip +为了能获取系统的回调通知，应用需要定义一个 service，并配置到 registry 中。例如，上面配置的 `app-svc`。 +::: \ No newline at end of file diff --git a/docs/zh/developer/develop/advanced/ai.md b/docs/zh/developer/develop/advanced/ai.md new file mode 100644 index 000000000..3cd40a397 --- /dev/null +++ b/docs/zh/developer/develop/advanced/ai.md @@ -0,0 +1,547 @@ +--- +outline: [2, 3] +--- + +# AI + +## API 前缀 + +`agent.{username}.olares.com/api/controllers/console/api` + +## 基本应用管理 API +### 获取 App 列表 +- **Request** + - **URL**: `/apps` + - **Method**: `GET` + - **URL Parameters**: `/apps?page=1&limit=30&name=Ashia` + :::tip + 本文档中列出的大多数 API 都需要`app_id`，可以从该 API 的 Response 中获取该`app_id`。 + ::: + +### 创建应用 +- **Request** + - **URL**: `/apps` + - **Method**: `POST` + - **Body Example**: + ```json + { + "name": "TEST", + "icon": "🤖", + "icon_background": "#FFEAD5", + "mode": "agent-chat", + "description": "JUST A TEST" + } + ``` + +### 获取应用细节 +- **Request** + - **URL**: `/apps/{uuid:app_id}` + - **Method**: `GET` + - **Body Example**: `null` + +### 删除应用 +- **Request** + - **URL**: `/apps/{uuid:app_id}` + - **Method**: `DELETE` + - **Body Example**: `null` + +### 复制应用 +- **Request** + - **URL**: `/apps/{uuid:app_id}/copy` + - **Method**: `POST` + - **Body Example**: + ```json + { + "name": "Ashia-2", + "icon": "🤖", + "icon_background": "#FFEAD5", + "mode": "agent-chat" + } + ``` + +### 应用重命名 +- **Request** + - **URL**: `/apps/{uuid:app_id}/name` + - **Method**: `POST` + - **Body Example**: + ```json + { + "name": "Ashia—34" + } + ``` + +### 修改应用图标 +- **Request** + - **URL**: `/apps/{uuid:app_id}/icon` + - **Method**: `POST` + - **Body Example**: + ```json + { + "icon": "heavy_check_mark" + } + ``` + +### 应用网页访问控制 +> 调整应用是否可网页访问。 +- **Request** + - **URL**: `/apps/{uuid:app_id}/site-enable` + - **Method**: `POST` + - **Body Example**: + ```json + { + "enable_site": true + } + ``` + +### 应用 API 访问控制 +> 调整应用是否可 API 访问 +- **Request** + - **URL**: `/apps/{uuid:app_id}/api-enable` + - **Method**: `POST` + - **Body Example**: + ```json + { + "enable_api": true + } + ``` + +## 应用 Function API +### 文本生成 +> 文本生成型应用的执行接口 +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-messages` + - **Method**: `POST` + - **Body Example**: + :::details + ```json + { + "inputs": { + "query": "Hello～" + }, + "model_config": { + "pre_prompt": "{{query}}", + "prompt_type": "simple", + "chat_prompt_config": {}, + "completion_prompt_config": {}, + "user_input_form": [ + { + "paragraph": { + "label": "Query", + "variable": "query", + "required": true, + "default": "" + } + } + ], + "dataset_query_variable": "", + "opening_statement": null, + "suggested_questions_after_answer": { + "enabled": false + }, + "speech_to_text": { + "enabled": false + }, + "retriever_resource": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false, + "type": "", + "configs": [] + }, + "more_like_this": { + "enabled": false + }, + "model": { + "provider": "openai_api_compatible", + "name": "nitro", + "mode": "chat", + "completion_params": { + "temperature": 0.7, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 0, + "max_tokens": 512 + } + }, + "text_to_speech": { + "enabled": false, + "voice": "", + "language": "" + }, + "agent_mode": { + "enabled": false, + "tools": [] + }, + "dataset_configs": { + "retrieval_model": "single", + "datasets": { + "datasets": [] + } + }, + "file_upload": { + "image": { + "enabled": false, + "number_limits": 3, + "detail": "high", + "transfer_methods": [ + "remote_url", + "local_file" + ] + } + } + }, + "response_mode": "streaming" + } + ``` + ::: + +## 文本生成停止 +> 文本生成型应用执行中断任务接口 +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-messages/{string:task_id}/stop` + - **Method**: `POST` + - **Body Example**: `null` + :::tip + 该 API 中所需的 `task_id` 可以从[文本生成](#文本生成) API 的 Response（流式传输）中获取。 + ::: + +## 聊天 +> 聊天型应用的执行接口 +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages` + - **Method**: `POST` + - **Body Example**: + :::details + ```json + { + "response_mode": "streaming", + "conversation_id": "", + "query": "Hello～", + "inputs": {}, + "model_config": { + "pre_prompt": "", + "prompt_type": "simple", + "chat_prompt_config": {}, + "completion_prompt_config": {}, + "user_input_form": [], + "dataset_query_variable": "", + "opening_statement": "", + "more_like_this": { + "enabled": false + }, + "suggested_questions": [], + "suggested_questions_after_answer": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "voice": "", + "language": "" + }, + "speech_to_text": { + "enabled": false + }, + "retriever_resource": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "agent_mode": { + "max_iteration": 5, + "enabled": true, + "tools": [], + "strategy": "react" + }, + "dataset_configs": { + "retrieval_model": "single", + "datasets": { + "datasets": [] + } + }, + "file_upload": { + "image": { + "enabled": false, + "number_limits": 2, + "detail": "low", + "transfer_methods": [ + "local_file" + ] + } + }, + "annotation_reply": { + "enabled": false + }, + "supportAnnotation": true, + "appId": "2c937aae-f4f2-4cf9-b6e2-f2f2756858c0", + "supportCitationHitInfo": true, + "model": { + "provider": "openai_api_compatible", + "name": "nitro", + "mode": "chat", + "completion_params": { + "temperature": 2, + "top_p": 1, + "frequency_penalty": 0, + "presence_penalty": 0, + "max_tokens": 512, + "stop": [] + } + } + } + } + ``` + ::: + + +## 聊天停止 +> 聊天型应用执行中断任务接口 +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages/{string:task_id}/stop` + - **Method**: `POST` + - **Body Example**: `null` + :::tip + 该 API 中所需的 `task_id` 可以从[聊天](#聊天) API 的 Response（流式传输）中获取。 + ::: + +### 获取会话列表（文本生成） +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-conversations` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/completion-conversations?page=1&limit=30` + :::tip + 下面列出的会话（文本生成）API 需要 `conversation_id`，可以从该 API 的 Response 中获取。 + ::: + +### 获取会话细节（文本生成） +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-conversations/{uuid:conversation_id}` + - **Method**: `GET` + - **Body Example**: `null` + :::tip + 下面列出的会话（文本生成）API 需要 `message_id`，可以从该 API 的 Response 中获取。 + ::: + +### 删除会话细节（文本生成） +- **Request** + - **URL**: `/apps/{uuid:app_id}/completion-conversations/{uuid:conversation_id}` + - **Method**: `DELETE` + - **Body Example**: `null` + +### 获取会话列表（聊天） +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-conversations` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/chat-conversations?page=1&limit=30` + :::tip + 下面列出的会话（聊天）API 需要 `conversation_id`，可以从该 API 的 Response 中获取。 + ::: + +### 获取会话细节（聊天） +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-conversations/{uuid:conversation_id}` + - **Method**: `GET` + - **Body Example**: `null` + :::tip + 下面列出的会话（对话）API 需要 `message_id`，可以从该 API 的 Response 中获取。 + ::: + +### 删除会话细节（聊天） +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-conversations/{uuid:conversation_id}` + - **Method**: `DELETE` + - **Body Example**: `null` + +### 推荐问题（聊天） +> 在对话型应用中，获取 AI 给出回复后可以提出的建议问题 +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages/{uuid:message_id}/suggested-questions` + - **Method**: `GET` + - **Body Example**: `null` + +### 获取消息列表（聊天） +- **Request** + - **URL**: `/apps/{uuid:app_id}/chat-messages` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/chat-messages?conversation_id={conversation_id}` + +### 消息反馈 +> 对应用消息反馈喜欢或不喜欢 +- **Request** + - **URL**: `/apps/{uuid:app_id}/feedbacks` + - **Method**: `POST` + - **Body Example**: + ```json + { + "rating": "like" // "like" | "dislike" | null + } + ``` + +### 消息标注 +> 对来自应用的消息进行标注（文本生成） +- **Request** + - **URL**: `/apps/{uuid:app_id}/annotations` + - **Method**: `POST` + - **Body Example**: + ```json + { + "message_id": "2b79fdad-e513-45ef-9532-8de5086cb81c", + "question": "query:How are you?", + "answer": "some answer messages" + } + ``` + +### 消息标注统计 +> 获取应用当前消息的注释条数 +- **Request** + - **URL**: `/apps/{uuid:app_id}/annotations/count` + - **Method**: `GET` + - **Body Example**: `null` + + +### 获取消息细节（聊天） +- **Request** + - **URL**: `/apps/{uuid:app_id}/messages/{uuid:message_id}` + - **Method**: `GET` + - **Body Example**: `null` + +## 高级应用管理 API + +### 模型配置 +- **Request** + - **URL**: `/apps/{uuid:app_id}/model-config` + - **Method**: `POST` + - **Body Example**: + :::details + ```json + { + "pre_prompt": "", + "prompt_type": "simple", + "chat_prompt_config": {}, + "completion_prompt_config": {}, + "user_input_form": [], + "dataset_query_variable": "", + "opening_statement": "", + "suggested_questions": [], + "more_like_this": { + "enabled": false + }, + "suggested_questions_after_answer": { + "enabled": false + }, + "speech_to_text": { + "enabled": false + }, + "text_to_speech": { + "enabled": false, + "language": "", + "voice": "" + }, + "retriever_resource": { + "enabled": false + }, + "sensitive_word_avoidance": { + "enabled": false + }, + "agent_mode": { + "max_iteration": 5, + "enabled": true, + "strategy": "react", + "tools": [] + }, + "model": { + "provider": "openai_api_compatible", + "name": "nitro", + "mode": "chat", + "completion_params": { + "frequency_penalty": 0, + "max_tokens": 512, + "presence_penalty": 0, + "stop": [], + "temperature": 2, + "top_p": 1 + } + }, + "dataset_configs": { + "retrieval_model": "single", + "datasets": { + "datasets": [] + } + }, + "file_upload": { + "image": { + "enabled": false, + "number_limits": 2, + "detail": "low", + "transfer_methods": [ + "local_file" + ] + } + } + } + ``` + ::: + +### 修改应用基本信息 +- **Request** + - **URL**: `/apps/{uuid:app_id}/site` + - **Method**: `POST` + - **Body Example**: + ```json + { + "title": "Ashias-23", + "icon": "grin", + "icon_background": "#000000", + "description": "How do you do~" + } + ``` +### 重新生成公开访问的 URL +> 重新生成应用的公共访问 URL +- **Request** + - **URL**: `/apps/{uuid:app_id}/site/access-token-reset` + - **Method**: `POST` + - **Body Example**: `null` + +## 应用统计 API +### 全部消息数统计 +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/daily-conversations` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/daily-conversations?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### 活跃用户统计 +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/daily-end-users` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/daily-end-users?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### 费用消耗统计 +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/token-costs` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/token-costs?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### 平均会话互动数统计 +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/average-session-interactions` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/average-session-interactions?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### 用户满意度统计 +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/user-satisfaction-rate` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/user-satisfaction-rate?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### 平均响应时间统计 +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/average-response-time` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/average-response-time?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` + +### Token 输出速度统计 +- **Request** + - **URL**: `/apps/{uuid:app_id}/statistics/tokens-per-second` + - **Method**: `GET` + - **URL Parameters**: `/apps/{uuid:app_id}/statistics/tokens-per-second?start=2024-04-19%2016%3A28&end=2024-04-26%2016%3A28` diff --git a/docs/zh/developer/develop/advanced/cli.md b/docs/zh/developer/develop/advanced/cli.md new file mode 100644 index 000000000..a23cc80a9 --- /dev/null +++ b/docs/zh/developer/develop/advanced/cli.md @@ -0,0 +1,182 @@ +# CLI + + +## Olares Installation Script in Command Line + +```sh +# Environment variable +export KUBE_TYPE="k8s" # k8s or k3s (k3s is default) +export REGISTRY_MIRRORS="http://dockermirror/" # Docker registry mirror URL +export LOCAL_GPU_ENABLE=1 # Enable local GPU support if hardware is installed on the node +export LOCAL_GPU_SHARE=1 # Enable GPU sharing + +# Execute installation +curl -fsSL https://olares.sh | bash - +``` + +## Olares Uninstallation Script + +- For Olares installed on Linux, Raspberry Pi, and Windows (Windows Subsystem for Linux): + + ```sh + cd install-wizard && bash uninstall_cmd.sh + ``` + +- For Olares Installed on Mac: + + ```sh + bash uninstall_macos.sh + ``` + +## Resolve IP Change Issue + +Services within the Kubernetes cluster rely on stable IPs and DNS resolution provided by the cluster's internal DNS. When you change the location of your Olares, its IP address changes. This can disrupt proper DNS resolution for your cluster and make Olares inaccessible. + +To resolve this issue, run the following command in Ubuntu in your new network environment: + +```sh +cd install-wizard && bash change_ip.sh +``` + +:::info +This command is not applicable to Olares on macOS yet. +::: + +## Add an Olares node locally + +**Before Install** +- Get the `internal IP address` of the **Master** node. +- Add the current machine's `public key` to the `authorized_keys` of the user who logged into the **Master** node. + +```sh +VERSION="1.3.0" # Version of Olares installed on the master node +curl -LO https://github.com/beclab/olares/releases/download/${VERSION}/install-wizard-v${VERSION}.tar.gz + +mkdir -p install_wizard +cd install_wizard && tar zxvf ../install-wizard-${VERSION}.tar.gz + +bash ./publicAddnode.sh +``` + +During the installation process, you will be asked to enter relevant information about the **Master node**. Please input as instructed. + +## Add a hard drive locally + +**Before Install** +- Insert the hard drive, then format it and create a filesystem in the operating system. The recommended filesystem is `XFS`. +- Create a new empty directory that aligns with the previous data directory. For example, if the previous system installation data directory was `/olares/data/minio/vol1`, the new directory should be `/olares/data/minio/vol2`. +- Mount the new hard drive at `/olares/data/minio/vol2`. + +```sh +VERSION="1.3.0" # Version of Olares installed on the master node +curl -LO https://github.com/beclab/olares/releases/download/${VERSION}/install-wizard-v${VERSION}.tar.gz + +mkdir -p install_wizard +cd install_wizard && tar zxvf ../install-wizard-${VERSION}.tar.gz + +bash scale_minio.sh -a driver -v /olares/data/minio/vol2 +``` + +If you are adding multiple hard drives, you can do it simultaneously. For instance, you mounted hard drives at: +``` +/olares/data/minio/vol2 +/olares/data/minio/vol3 +... +/olares/data/minio/voln +``` +you can add them all with +```sh +bash scale_minio.sh -a driver -v /olares/data/minio/vol{2...n} +``` + +## Add a Hard Drive Node + +You can also add hard drives to a new node machine separately from the Master node. + +**Prerequisites** +- The master node must be in multi-hard drive mode or have multiple partitions mounted. +- The new node should also be in multi-hard drive or multi-partition mode. + +**Before Install** +- Get the `internal IP address` of the **Master** node, e.g., 192.168.1.100 +- Get the `internal IP address` of the **Target** node, e.g., 192.168.1.101 +- Add the **Target** node machine's `public key` to the `authorized_keys` of the user who logged into the master node, e.g., ubuntu +- Format the hard drives, create `XFS` filesystem +- Create contiguous data storage directories and mount them to multiple hard drives or partitions. e.g.
+ `/olares/data/minio/vol1`
+ `/olares/data/minio/vol2`
+ `/olares/data/minio/vol3`
+ `/olares/data/minio/vol4`
+ +```sh +VERSION="1.3.0" # Version of Olares installed on the master node +curl -LO https://github.com/beclab/olares/releases/download/${VERSION}/install-wizard-v${VERSION}.tar.gz + +mkdir -p install_wizard +cd install_wizard && tar zxvf ../install-wizard-${VERSION}.tar.gz + +bash scale_minio.sh -a node -v /olares/data/minio/vol{1...4} \ + -u ubuntu \ + -s 192.168.1.100 \ + -n 192.168.1.101 +``` + +## Install a Custom Version of Olares + +To debug a program that involves the startup process of Olares, you may need to build a temporary local version of Olares and replace the service you're debugging. + +In other scenarios, consider using Control Hub or kubectl to update services. + +```sh +# Clone +git clone https://github.com/beclab/olares + +# Build +cd olares +bash scripts/build.sh + +# Modify your application/service yaml + +# Install +pkg_path=$(pwd) +mkdir -p ~/install-wizard && cd ~/install-wizard +tar zxvf ${pkg_path}/install-wizard-debug.tar.gz + +# Any version number will do, for example 0.0.0-DEBUG +make install VERSION=0.0.0-DEBUG + +# Uninstall +cd ~/install-wizard +make uninstall +``` + +## Restore Olares from a Snapshot + +If you have enabled the backup feature of **Olares** and have backed up system data to **S3 storage**, you can select a snapshot from a specific point in time to restore Olares. + + +```sh +export KUBE_TYPE=k8s # k8s / k3s +export REGISTRY_MIRRORS="http://dockermirror/" + +export TERMINUS_BACKUP_NAME= +export BACKUP_S3_REPOSITORY= +export BACKUP_SNAPSHOT_ID= + +export AWS_ACCESS_KEY_ID= +export AWS_SECRET_ACCESS_KEY= + +export CLUSTER_ID= + +VERSION="1.3.0" # Version of Olares installed on the master node +curl -LO https://github.com/beclab/olares/releases/download/${VERSION}/install-wizard-v${VERSION}.tar.gz + +mkdir -p install_wizard +cd install_wizard && tar zxvf ../install-wizard-${VERSION}.tar.gz + +bash publicRestoreInstaller.sh +``` + +If you back up your data to the **Olares Space**, you can directly download the restoration script from **Olares Space**. + +![restore](images/restore.jpg) \ No newline at end of file diff --git a/docs/zh/developer/develop/advanced/cookie.md b/docs/zh/developer/develop/advanced/cookie.md new file mode 100644 index 000000000..5175483f7 --- /dev/null +++ b/docs/zh/developer/develop/advanced/cookie.md @@ -0,0 +1,23 @@ +# Cookie + +Olares 系统中采用 SSO 的模式来为整个系统（包括所有安装的应用）实现授权认证。SSO 认证模式采用无侵入设计，使用 cookie 作为认证的凭证。 + +系统会在认证登录后设置两个 cookie： + +- **authelia_session** + + cookie 内容为 SSO 的 session id。作用域为用户的 Olares domain， `.olares.com`。 + +- **auth_token** + + 用户认证的 authorization token。作用域为用户的 Olares domain， `.olares.com`。 + +为避免 cookie 冲突，任何应用（包括系统的内建应用，三方应用）都不可以设置 cookie 到用户的域，只可设置到应用自己的域下面。 + +要使用这个功能只需要在应用 chart 的 [OlaresManifest.yaml](../package/manifest.md#resetcookie) 中申明： + +```yaml +options: + resetCookie: + enabled: true +``` diff --git a/docs/zh/developer/develop/advanced/database.md b/docs/zh/developer/develop/advanced/database.md new file mode 100644 index 000000000..4096726d2 --- /dev/null +++ b/docs/zh/developer/develop/advanced/database.md @@ -0,0 +1,64 @@ +# 数据库 + +Olares 系统中为所有应用提供了三种最流行的数据存储集群，覆盖 RDS、NoSQL、Cache 三种数据存储场景。 + +## RDS + +系统部署了 PostgreSQL，并且提供两种模式的数据库。 + +- 单机模式的 PostgreSQL，提供最常用的 RDS 数据库层的功能。 +- 分布式 PostgreSQL 扩展，Citus。提供数据库的分布式横向扩展能力。 + +应用在设置数据库申请的时候，可以快速指定要采用数据库类型。 + +```yaml +middleware: +postgres: + username: postgres + databases: + - name: db + distributed: true # 是否需要分布式数据库 +``` + +当应用选用了 Citus，在系统对 PostgreSQL 做横向扩展副本时，会自动将数据库表做 sharding，并且执行 rebalance。 + +## NoSQL + +Olares 中默认未部署 NoSQL 集群，但可以从应用市场中安装。要设置 NoSQL 集群，管理员需要安装 [**MongoDB**](https://market.olares.com/middleware/mongodb) 中间件。 安装后，[Percona Operator for MongoDB](https://github.com/percona/percona-server-mongodb-operator) 会自动管理 **MongoDB** 集群。然后，用户可以水平扩展 **MongoDB** 集群副本，以及对数据库执行备份和恢复操作。 + +你可以在 [OlaresManifest.yaml](../package/manifest.md#middleware) 中指定 MongoDB 的详细配置，如下所示： + +```yaml +middleware: + mongodb: + username: mongodb + databases: + - name: db0 + - name: db1 +options: + dependencies: + - name: olares + type: system + version: '>=1.6.0-0' + - name: mongodb + version: ">=6.0.0-0" + type: middleware +``` + +## Cache + +在 Cache 的集群方面，Olares 选用了 Redis Cluster。并通过定制化的[Redis Cluster Operator](https://github.com/beclab/redis-cluster-operator) 对集群进行管理，实现其云原生化。可以做到很方便简单的横向副本扩展。 + +同时，为了保证 Redis 集群数据，用户与用户之间，应用与应用之间数据隔离无干扰，系统还增加了一个 Redis 集群代理，实现数据的`命名空间`隔离，并且对应用开发者来说，完全无感知，无需关心。 + +此外，这个集群代理还提供方便的集群连接功能，在应用中无需移植单例版的 Redis Client 到 Redis Cluster client。大大的简化了应用的代码修改工作。 + +``` +middleware: + redis: + password: password + namespace: db0 +``` +:::info 注意 +由于 Olares 采用的是 Redis Cluster 版本，所以开发者在使用时需详细了解 Redis Cluster 的使用限制。 +::: \ No newline at end of file diff --git a/docs/zh/developer/develop/advanced/file-upload.md b/docs/zh/developer/develop/advanced/file-upload.md new file mode 100644 index 000000000..800785c5d --- /dev/null +++ b/docs/zh/developer/develop/advanced/file-upload.md @@ -0,0 +1,174 @@ +--- +outline: [2, 3] +--- + +# 文件上传 + +Olares 作为一个云端系统，存在很多将本地文件上传到云端的场景。Olares 应用运行时提供了一个通用的 file-upload 组件。简化应用对文件上传需求的开发。同时，file-upload 组件还提供了断点续传功能。 + +## 如何安装 + +只要在应用 chart 的 [OlaresManifest.yaml](../package/manifest.md#file-upload) 中申明 +```yaml +upload: + fileType: + - pdf + dest: /appdata + limitedSize: 3729747942 +``` + +## 前端接口对接 + +:::info 注意 +单次上传大小限制为 10M，大于 10M 需要使用分片断点续传功能。 +::: + + +## 上传 + +该接口用于上传文件到服务器并获取文件id和状态。 +:::details 示例 +**Request** +```sh +curl --location 'http://host:40030/upload/' \ +--form 'storage_path="./testupload/"' \ +--form 'file_relative_path="1.csv"' \ +--form 'file_type="csv"' \ +--form 'file_size="1937"' +``` +**Response** +```json +{ + "code": 0, + "message": "success", + "data": { + "id": "b0b76f02bdb8ee3269602c983c4a2aeb", + "offset": 0, + "file_relative_path": "1.csv", + "file_type": "csv", + "file_size": 1937, + "storage_path": "./testupload/" + } +} +``` +::: +- **Request** + + - **URL**: `/upload/` + + - **Method**: `POST` + + - **Body**: + ``` json + "mode": "formdata", //请求体为 multipart/form-data 格式 + "body parameters": { + "storage_path": string, //必填，文件在服务器上的存储文件夹，该文件夹必须存在， + "file_relative_path": string, //必填，文件相对于 storage_path 的路径，必须包含文件名。如果为文件夹，以“/”结尾。 + "file_type": string, //必填，文件类型 + "file_size": integer, //必填，文件大小 + } + ``` +- **Success Response** + + 响应体为 JSON 格式，包含以下字段： + - **状态码** : `200 OK` + ```json + "code": integer, // 响应码，0 表示成功，非零表示失败。 + "message": string, // 响应消息，成功时为 "success"，失败时为相应的错误消息。 + "data":{ //响应数据，成功时包含以下字段（上传文件夹时无该字段）： + "id": string, // 文件唯一标识符 + "offset": integer, // 文件上传的偏移量 + "file_relative_path": string, + "file_type": string, + "file_size": integer, + "storage_path": string + } + ``` + +- **错误情况** + - **状态码** : `400 Bad Request` + > 请求参数不合法或缺失。 + - **状态码** : `500 Internal Server Error` + > 服务器内部错误，例如创建文件夹失败或保存文件信息失败。 + +### 断点续传 + +该接口用于继续上传文件的剩余部分。 +:::details 示例 +**Request** +```sh +curl --location --request PATCH 'http://host:40030/upload/b0b76f02bdb8ee3269602c983c4a2aeb' \ +--form 'file=@"/Users/yangtao/Downloads/1.csv"' \ +--form 'upload_offset="0"' +``` +**Response** +```json +{ + "code": 0, + "message": "File uploaded successfully", + "data": { + "id": "b0b76f02bdb8ee3269602c983c4a2aeb", + "offset": 1937, + "file_name": "1.csv", + "file_type": "csv", + "file_size": 1937, + "storage_path": "./testupload" + } +} +{ + "code": 0, + "message": "Continue uploading", + "data": { + "id": "e3133b0f838124ff3ebcc9cb14774f26", + "offset": 1048576, + "file_name": "1.pdf", + "file_type": ".pdf", + "file_size": 10296258, + "storage_path": "./testupload" + } +} +``` +::: + +- **Request** + + - **URL**: `http://host:40030/upload/{uid}` + + - **Method**: `PATCH` + + - **Body**: + ``` json + "mode": "formdata", //请求体为 multipart/form-data 格式 + "body parameters": { + "file": string, //必填，要上传的文件。请使用 multipart/form-data 格式进行文件上传。 + "upload_offset": integer, //必填，文件上传的偏移量，之前已上传的文件大小。 + } + "url parameters": { + "uid": string, //必填，文件的唯一标识符。可以从上传 API 的 Response 数据中获取。 + } + ``` +- **Success Response** + +响应体为 JSON 格式，包含以下字段： + - **状态码** : `200 OK` + ```json + "code": integer, // 响应码，0 表示成功，非零表示失败。 + "message": string, // 响应消息，成功时为 "File uploaded successfully"，失败时为相应的错误消息。 + "data":{ // 响应数据，成功时包含以下字段： + "id": string, // 文件唯一标识符 + "offset": integer, // 文件上传的偏移量 + "file_relative_path": string, + "file_type": string, + "file_size": integer, + "storage_path": string + } + ``` + +- **错误情况** + - **状态码** : `400 Bad Request` + > 请求参数不合法或缺失。 + ```json + { "code": 1, "message": "Invalid upload ID" } + ``` + - **状态码** : `500 Internal Server Error` + > 服务器内部错误，例如创建文件夹失败、保存文件信息失败或移动文件失败。 \ No newline at end of file diff --git a/docs/zh/developer/develop/advanced/frontend.md b/docs/zh/developer/develop/advanced/frontend.md new file mode 100644 index 000000000..fce2e39cb --- /dev/null +++ b/docs/zh/developer/develop/advanced/frontend.md @@ -0,0 +1,9 @@ +# Frontend + +## 视觉规范 + +https://w8wvyn24o5.feishu.cn/wiki/Im1nwwPCRiIcGCkBy8qc1vNknVd + +## core 库 + +## UI 库 diff --git a/docs/zh/developer/develop/advanced/image-6.png b/docs/zh/developer/develop/advanced/image-6.png new file mode 100644 index 000000000..e09d75e05 Binary files /dev/null and b/docs/zh/developer/develop/advanced/image-6.png differ diff --git a/docs/zh/developer/develop/advanced/images/restore.jpg b/docs/zh/developer/develop/advanced/images/restore.jpg new file mode 100644 index 000000000..84731a58a Binary files /dev/null and b/docs/zh/developer/develop/advanced/images/restore.jpg differ diff --git a/docs/zh/developer/develop/advanced/index.md b/docs/zh/developer/develop/advanced/index.md new file mode 100644 index 000000000..b03639b63 --- /dev/null +++ b/docs/zh/developer/develop/advanced/index.md @@ -0,0 +1,14 @@ +# Advanced + +1. [Terminus Info](./terminus-info) +2. [Service Provider](./provider.md) +3. [AI](./ai.md) +4. [Cookie](./cookie.md) +5. [数据库](./database.md) +6. [账户](./account.md) +7. [应用市场](./market.md) +8. [Websocket](./websocket.md) +9. [文件上传](./file-upload.md) +10. [密钥](./secret.md) +11. [Kubesphere](./kubesphere.md) + diff --git a/docs/zh/developer/develop/advanced/kubesphere.md b/docs/zh/developer/develop/advanced/kubesphere.md new file mode 100644 index 000000000..ff81f365f --- /dev/null +++ b/docs/zh/developer/develop/advanced/kubesphere.md @@ -0,0 +1,14 @@ +# Kubesphere + +Olares 集成了 Kubesphere 的许多高级功能，如多用户系统和集群数据监控。要从 Kubesphere** 安装官方 console 工具，请从 Olares 代码存储库下载并安装它。 + +```sh +curl -LO https://github.com/Above-Os/terminus-os/raw/main/third-party/ks-console/ks-console-v3.3.0.tgz + +# username 为 Olares 的登录用户 +sudo helm install console ./ks-console-v3.3.0.tgz \ + -n user-space- \ + --set username= +``` + +安装后，刷新桌面。即可在 Olares 中看到 Console 的图标。 打开 Console，可用 Olares ID 和密码登录。 diff --git a/docs/zh/developer/develop/advanced/market.md b/docs/zh/developer/develop/advanced/market.md new file mode 100644 index 000000000..411ddd192 --- /dev/null +++ b/docs/zh/developer/develop/advanced/market.md @@ -0,0 +1,79 @@ +# 应用市场 + +开发者可利用应用市场提供的 Provider 接口，在自己开发的应用（比如，三方 应用市场扩展）中调用安装、卸载接口来安装或卸载应用。 + +Provider 的申请和调用方法可以详细阅读 [Service Provider](./provider.md) + +应用市场提供的 Provider + +| Group | version | dataType | ops | +| ---------------- | ------- | -------- | ----------------------------- | +| service.appstore | v1 | app | InstallDevApp UninstallDevApp | + +## 安装接口 +- **Request** + - **URL**:
`http://$OS_SYSTEM_SERVER/system-server/v1alpha1/app/service.appstore/v1/InstallDevApp` + + - **Method**: `POST` + + - **Header** + ```http + X-Authorization: token # cookie 中的 auth_token + X-Access-Token: access_token # provider 授权接口获取的 access token + ``` + + - **Body**（以 Golang struct 为例） + ```go + type InstallOptions struct { + App string `json:"appName"` //必须 + RepoUrl string `json:"repoUrl"` //必须 + CfgUrl string `json:"cfgUrl"` //可选 + Version string `json:"version"` //升级时需要 + Source string `json:"source"` //必须 + } + ``` + +- **请求返回** + ```go + type InstallationResponse struct { + Code int `json:"code"` + Msg string `json:"message,omitempty"` + Data InstallationResponseData `json:"data"` + } + + type InstallationResponseData struct { + UID string `json:"uid"` + } + ``` + +## 卸载接口 +- **Request** + - **URL**:
`http://$OS_SYSTEM_SERVER/system-server/v1alpha1/app/service.appstore/v1/UninstallDevApp` + + - **Method**: `POST` + + - **Header** + ```http + X-Authorization: token # cookie 中的 auth_token + X-Access-Token: access_token # provider 授权接口获取的 access token + ``` + + - **Body**（以 Golang struct 为例） + ```go + type UninstallData struct { + Name string `json:"name"` //required + } + ``` + +- **请求返回** + ```go + type InstallationResponse struct { + Code int `json:"code"` + Msg string `json:"message,omitempty"` + Data InstallationResponseData `json:"data"` + } + + type InstallationResponseData struct { + UID string `json:"uid"` + } + ``` \ No newline at end of file diff --git a/docs/zh/developer/develop/advanced/notification.md b/docs/zh/developer/develop/advanced/notification.md new file mode 100644 index 000000000..3217eedf2 --- /dev/null +++ b/docs/zh/developer/develop/advanced/notification.md @@ -0,0 +1,4 @@ +# Notification + +https://w8wvyn24o5.feishu.cn/wiki/SDLsw7KTAiohe5kmYM4cyNeCnCd +https://w8wvyn24o5.feishu.cn/wiki/E8RzwY3NAiRT8UkwYxQc9Hndnbf diff --git a/docs/zh/developer/develop/advanced/provider.md b/docs/zh/developer/develop/advanced/provider.md new file mode 100644 index 000000000..bdc7d8306 --- /dev/null +++ b/docs/zh/developer/develop/advanced/provider.md @@ -0,0 +1,117 @@ +# Service Provider + +APP 的开发者可在应用的 Chart 中配置 `ProviderRegistry` 或者请求调用其他 Provider 的权限。 + +## 申明 Provider + +```yaml +apiVersion: sys.bytetrade.io/v1alpha1 +kind: ProviderRegistry +metadata: + # provider 名称，需要加入namespace，避免重复 + name: provider-{{ .Release.Namespace }} + + # provider registry需要安装到user-system下面 + namespace: user-system-{{ .Values.bfl.username}} +spec: + version: v2 # 最新版本是 v2，系统同时兼容 v1 版本 + + # provider 的 dataType。建议加上 app name 避免重复 + dataType: legacy_{{ .Release.Name }} + deployment: {{ .Release.Name }} + description: {{ .Release.Name }} legacy api v2 + + # provider 可访问的服务。格式通常为 .: + endpoint: {{ .Release.Name }}-svc.{{ .Release.Namespace }}:1234 + + # provider 的组名。建议加上 app name 避免重复 + group: api.{{ .Release.Name }} + kind: provider + namespace: "{{ .Release.Namespace }}" + opApis: + # API 的名称 + - name: AppApi + # API 的 URL + uri: /api +status: + state: active +``` + +## 申请 Provider 的访问权限 + +可在 [OlaresManifest.yaml](../package/manifest.md#sysdata) 中配置： + +```Yaml +sysData: +- appName: providerapp # API provider 的 app name。ProviderRegistry v2 版本必填 + port: 8888 # provider service 的端口号 + + # provider 的默认域名格式为 -svc.-:。如果 service name 和 app namespace 不是默认格式，可以在以下字段中指定 + svc: app-svc # service 名称。ProviderRegistry v2 版本可选 + namespace: ns # app 的 namespace。ProviderRegistry v2版本可选 + + version: v2 # ProviderRegistry 的版本 + dataType: legacy_{{ .Release.Name }} # ProviderRegistry 中定义的 dataType + group: api.{{ .Release.Name }} # ProviderRegistry 中定义的组名 + ops: + - AppApi # ProviderRegistry 中定义的 opApis 名称 +``` + +配置完成后，你可以将访问密钥(`access key`)和访问密钥(`access secret`)添加到应用 chart 的模板中。它们将在安装过程中被注入以供授权使用。 + +```yaml +env: + - name: OS_SYSTEM_SERVER + value: system-server.user-system-{{ .Values.bfl.username }} + - name: OS_APP_SECRET + + # 应用名称在应用 chart 中定义 + value: "{{ .Values.os..appSecret }}" + - name: OS_APP_KEY + value: "{{ .Values.os..appKey }}" +``` + +你可以在代码中使用这三个环境变量来调用 Provider。以 curl 为例： + +1. 获取 access token，有效时间 5 分钟。token 加密算法：bcrypt(`app key` `timestamp` `app secret`) 。默认成本值为 10。 + + ```sh + now=$(date +%s) + token=$(htpasswd -nbBC 10 USER "${OS_APP_KEY}${now}${OS_APP_SECRET}"|awk -F":" '{print $2}') + + curl -X POST http://${OS_SYSTEM_SERVER}/permission/v1alpha1/access -H "content-type: application/json" \ + -d "{ \ + \"app_key\": \"${OS_APP_KEY}\", \ + \"timestamp\": ${now}, \ + \"token\": \"${token}\", \ + \"perm\": { \ + \"group\": \"service.bfl\", \ + \"dataType\": \"app\", \ + \"version\": \"v1\", \ + \"ops\": [ \ + \"InstallDevApp\" \ + ] \ + } \ + }' + ``` + +2. 系统将返回： + ```json + { + "code": 0, + "message": "success", + "data": { + "access_token": "JDJ5JDEwJE5Wbk9vbFpoLjJlSGxhUUpRY1IwRmVZVjFBWmUxUi5LOXNuQWJmVjRnN29xNWVVaFhPWmV5" + } + } + ``` + +3. 你可以用返回的 token 去调用 provider 的接口： + + ```sh + # 地址格式 http://${OS_SYSTEM_SERVER}/system-server/v1alpha1//// + curl http://${OS_SYSTEM_SERVER}/system-server/v1alpha1/app/service.bfl/v1/InstallDevApp \ + -H "content-type: application/json" \ + -H "X-Access-Token: ${access_token}" \ + -d '{"data":"post to provider"}' + ``` diff --git a/docs/zh/developer/develop/advanced/rss.md b/docs/zh/developer/develop/advanced/rss.md new file mode 100644 index 000000000..b83bcc12c --- /dev/null +++ b/docs/zh/developer/develop/advanced/rss.md @@ -0,0 +1 @@ +# RSS diff --git a/docs/zh/developer/develop/advanced/secret.md b/docs/zh/developer/develop/advanced/secret.md new file mode 100644 index 000000000..252b6265b --- /dev/null +++ b/docs/zh/developer/develop/advanced/secret.md @@ -0,0 +1,132 @@ +--- +outline: [2, 3] +--- + +# 密钥 + +在应用中，通常需要保存一些重要的用户信息，例如外部系统的“密码”和“访问令牌”。Olares 提供了一个统一的 Vault 安全存储各种密钥（基于 Infisical）。 + +应用只需要做简单的申请，即可获得接口访问权限。申请方式是在应用 Chart 的 [OlaresManifest.yaml](../package/manifest.md#sysdata) 中添加 `sysData` 权限，例如： + +```yaml +permission: + sysData: + - dataType: secret + group: secret.infisical + version: v1 + ops: + - RetrieveSecret?workspace=your-app # 每个应用申明自己独立的workspace + - CreateSecret?workspace=your-app + - DeleteSecret?workspace=your-app + - UpdateSecret?workspace=your-app + - ListSecret?workspace=your-app +``` + +## 调用接口 + +你可以像请求其他 Provider 一样调用 API。使用 ops 的全名（包括 workspace 参数）作为 URI。 + +调用接口时需要加入 header。 +```http +X-Authorization: +``` + +### RetrieveSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":{ + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod + } + } + ``` + +### CreateSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":"" + } + ``` + + +### DeleteSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":"" + } + ``` + + +### UpdateSecret +- **Request Body** + ```json + { + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":"" + } + ``` + +### ListSecret +- **Request Body** + ```json + { + "env": "string" // environment of secret, test | dev | staging | prod (default) + } + ``` + +- **Success Response** + ```json + { + "code": http.StatusOK, // 200 is ok + "message": "", + "data":{ + "name": "string", // secret name + "value": "string", // secret value + "env": "string" // environment of secret, test | dev | staging | prod + } + } + ``` \ No newline at end of file diff --git a/docs/zh/developer/develop/advanced/terminus-info.md b/docs/zh/developer/develop/advanced/terminus-info.md new file mode 100644 index 000000000..a51c74171 --- /dev/null +++ b/docs/zh/developer/develop/advanced/terminus-info.md @@ -0,0 +1,37 @@ +# terminus-info + +terminus-info 是一个无需鉴权的接口，我们将一些系统可以对外展示的信息放在这里。可以理解为它是房子的门牌。 + +## 外部调用 + +``` +https://.olares.com/api/terminus-info +``` + +## 字段含义 + +```json +interface TerminusInfo { + terminusName: string; + wizardStatus: string; + selfhosted: boolean; + tailScaleEnable: boolean; + osVersion: string; + avatar: string; + loginBackground: string; + terminusId: string; +} +``` + +## 字段含义 + +| 字段 | 解释 | +| --------------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| terminusName | 用户的 Olares ID。格式是: `username@domain.com`。 | +| wizardStatus | Olares 的激活状态，有以下状态：
`wait_activate_vault`，`vault_activating`，`vault_activate_failed`，`wait_activate_system`，`system_activating`，`system_activate_failed`，`wait_activate_network`，`network_activating`，`network_activate_failed`，`wait_reset_password`, `completed`。
当状态为 `completed` 时，代表用户激活成功。在用户激活成功前，不推荐第三方程序进行太多业务相关的逻辑。 | +| selfhosted | 用户所在的 Olares 是否运行在 Olares Space 上 | +| tailScaleEnable | 用户是否激活了 TailScale，如果激活了私有入口只能通过 VPN 访问
用途：LarePass 在连接 Olares 时，不根据这个变量决定是否增加 local 访问。 | +| osVersion | Olares 的系统版本 | +| avatar | 用户的头像 | +| loginBackground | 登录界面的背景图 | +| terminusId | 用户在每次激活时，都会生成一个新的唯一 ID | diff --git a/docs/zh/developer/develop/advanced/websocket.md b/docs/zh/developer/develop/advanced/websocket.md new file mode 100644 index 000000000..7ac944e75 --- /dev/null +++ b/docs/zh/developer/develop/advanced/websocket.md @@ -0,0 +1,173 @@ +--- +outline: [2, 3] +--- + +# Websocket + +WebSocket 是现代前端开发中使用最广泛的技术之一。为了简化 Olares 应用的使用与开发，Olares 应用程序运行时提供了一个通用的 WebSocket 组件。 + +## 客户端 + +基于 JavaScript/TypeScript 的方式开发的客户端，采用 “ws” 库。 +应用服务提供 WebSocket 的路径格式：`wss://..olares.com/ws` + +### 发送消息 + +客户端发送 WebSocket 消息格式如下（支持其他格式）： +```json +{ + "event": "...", + "data": {...} +} +``` + +### Ping + +客户端需要定期发送 ping 包（30 秒一次），以维持 WebSocket 连接。（WebSocket 服务定期检查 ping 包，超时则会主动关闭该连接），ping 包数据格式如下（严格按照如下格式）： +```json +{ + "event": "ping", + "data": {} +} +``` + +## 应用 + +WebSocket 服务提供多种功能： +- 允许服务器通过广播消息或响应客户端发送的 WebSocket 消息与客户端进行通信。 +- 可用于关闭特定用户或连接 ID 的 WebSocket 连接。 +- 获取当前连接列表。 + +因为 WebSocket 与应用是部署在一个容器中的，所以直接访问 localhost 即可调用 WebSocket 服务。端口 `40010`。 + +### 广播消息 +```json +// URL：http://localhost:40010/tapr/ws/conn/send +// 请求方式：POST +// body +{ +"payload": {}, // 消息。 +"conn_id": "", // 连接 ID；用于响应客户端的单次 Ws 请求。按 users 广播时不要填写 connId +"users": ["", ""], // 指定用户，如果填写该字段，则是广播。广播场景下不要填写 connId +} + +// 响应示例 +{ +"code": 0, +"message": "success", +} +``` + +### 关闭客户端的 WebSocket 连接 +```json +// URL：http://localhost:40010/tapr/ws/conn/close +// 请求方式：POST +// body +{ +"conns": ["", ...], // 关闭指定连接 +"users": ["", ...], // 关闭指定用户的所有连接 +} + +// 响应示例 +{ +"code": 0, +"message": "success", +} +``` + +### 获取当前在线的连接列表 + +```json +// URL：http://localhost:40010/tapr/ws/conn/list +// 请求方式：GET +// 响应示例 +{ + "code": 0, + "message": "success", + "data": [ + { + "name": "", + "conns": [ + { + "id": "", // 连接 ID + "userAgent": "" + } + ] + } + ] +} +``` + +### WebSocket 转发客户端消息到应用 + +将转发到应用的客户端消息分为三种类型： +- 客户端连入 +- 客户端正常发送的消息 +- 客户端连接断开，如关闭浏览器，网络异常等。 + +**客户端连入** + +```json +// URL：http://localhost:3010/websocket/message +// 请求方式：POST +// body + +{ + "data": {}, + "action": "open", // action + "user_name": "", + "conn_id": "1" // WebSocket 连接 ID +} + +// 应用 App 接收到 open 的消息后，做相关处理。 +``` + +**客户端正常发送的消息** + +```json +// URL：http://localhost:3010/websocket/message +// 请求方式：POST +// header，会传递客户端的原始 Cookie 给后端应用 +Cookie: .... // v1.0.3 版本新增功能 + +// body +{ +"data": { ... }, // 客户端发到 WSGateway 的原始数据，内部结构为 {"event":"", "data": {...}} +"action": "message", // action +"user_name": "", +"conn_id": "1", // WebSocket 连接 ID +} + +// 应用 App 处理后通过“广播消息”的接口，将数据回传给客户端 + +``` + +**客户端连接断开** +>WebSocket 服务响应到 close 事件后回调应用 + +```json +// URL：http://localhost:3010/websocket/message +// 请求方式：POST +// body + +{ + "data": {}, + "action": "close", // action + "user_name": "", + "conn_id": "1" // WebSocket 连接 ID +} + +// 应用 App 接收到 close 的消息后，做相关处理。 +``` + +## 应用部署 WebSocket 服务 + +应用要使用这个功能只需要在应用 Chart 的 [OlaresManifest.yaml](../package/manifest.md#websocket) 中申明。 +```yaml +options: + websocket: + url: /ws/message + port: 8888 +``` + +WebSocket 是在客户端和应用之间承载消息转发的组件，所以应用端需要提供一个 API 接口，供 WebSocket 调用转发客户端的 ws 消息。比如，按上面的申明应用应提供接口名为：`/ws/message`，端口是 `8888`。 diff --git a/docs/zh/developer/develop/index.md b/docs/zh/developer/develop/index.md new file mode 100644 index 000000000..7060fad97 --- /dev/null +++ b/docs/zh/developer/develop/index.md @@ -0,0 +1,15 @@ +# 简介 + +在 Olares 上开发应用与当下主流的网站开发方法并没有太多区别，只需要额外了解一些 Olares 的基本概念，即可在 Olares 上开发应用。 + +- [Olares 的核心理念](../../manual/concepts/index.md) +- [了解 Olares 应用 Chart 的格式](./package/chart.md) + - [Olares 应用 Chart 包的结构](./package/chart.md) + - [OlaresManifest.yaml 的配置和字段说明](./package/manifest.md) + - [Olares 对 Helm 进行的字段扩展](./package/extension.md) + +- [探索我们的教程](./tutorial/) + - [了解 Olares 的开发工具 Devbox](./tutorial/studio) + - [创建首个应用](./tutorial/note/) +- [了解一些进阶的技巧](./advanced/) +- [提交应用到应用市场](./submit/) diff --git a/docs/zh/developer/develop/package/chart.md b/docs/zh/developer/develop/package/chart.md new file mode 100644 index 000000000..0739e3a94 --- /dev/null +++ b/docs/zh/developer/develop/package/chart.md @@ -0,0 +1,46 @@ +# Olares 应用 Chart 包的结构 + +Olares 应用 Chart 基于 Helm Chart 的基础结构，扩展 Olares 特有信息，主要为： +``` +|-- Chart.yaml # chart 的 metadata +|-- OlaresManifest.yaml # Olares 应用的配置 +|-- templates # chart 安装部署模版文件 +| |-- deployment.yaml # 应用部署脚本 +|-- values.yaml # chart 安装部署参数 +``` +:::info 注意 +为了使 `templates` 目录更易于理解，你可以将部署拆分为多个文件。 +::: + +- 应用 Chart 包示例： +``` +AppName +|-- Chart.yaml # 必选: 包含了 chart 信息的 YAML文件 +|-- OlaresManifest.yaml # 必选: 应用的配置文档 +|-- values.yaml # 必选: chart 默认的配置值 +|-- templates # 必选: 模板目录， 当和 values 结合时，可生成有效的 Kubernetes manifest 文件 +| |-- NOTES.txt # 可选: 包含简要使用说明的纯文本文件 +| |-- deployment.yaml # 定义应用安装的 Deployment +| |-- service.yaml # 定义应用提供 Entrance 的 Service +| |-- provider.yaml # 可选：如果需要暴露 Provider 接口 +|-- LICENSE # 可选: 包含 chart 许可证的纯文本文件 +|-- README.md # 可选: 可读的 README 文件 +``` + +- 推算算法 Chart 包示例： + +``` +RecommendName +|-- Chart.yaml # 必选: 包含了 chart 信息的 YAML 文件 +|-- OlaresManifest.yaml # 必选: 推荐算法的配置文档 +|-- values.yaml # 必选: chart 默认的配置值 +|-- templates # 必选: 模板目录， 当和 values 结合时，可生成有效的 Kubernetes manifest 文件 +| |-- NOTES.txt # 可选: 包含简要使用说明的纯文本文件 +| |-- train.yaml # 定义推荐算法 workflows 中的 train 流程 +| |-- prerank.yaml # 定义推荐算法 workflows 中的 prerank 流程 +| |-- rank.yaml # 定义推荐算法 workflows 中的 rank 流程 +| |-- embedding.yaml # 定义推荐算法 workflows 中的 embedding 流程 +|-- LICENSE # 可选: 包含 chart 许可证的纯文本文件 +|-- README.md # 可选: 可读的 README 文件 + +``` \ No newline at end of file diff --git a/docs/zh/developer/develop/package/extension.md b/docs/zh/developer/develop/package/extension.md new file mode 100644 index 000000000..7d934c87a --- /dev/null +++ b/docs/zh/developer/develop/package/extension.md @@ -0,0 +1,73 @@ +# Olares 对 Helm 进行的字段扩展 + +在安装过程中，Olares 使用 [OlaresManifest.yaml](manifest.md) 中的配置将扩展字段注入到应用程序中。 + +这些扩展字段信息，可以在模版中直接引用，而无需在 values.yaml 中事先定义 （如果 values.yaml 中有相同的定义，会被系统覆盖）。 + + +- 用户信息 + + | 变量 | 类型 | 说明 | + |----------------------|--------|------------| + | .Values.bfl.username | String | 当前安装应用的用户名 | + | .Values.user.zone | String | 当前用户的域名 | + +- 地址信息 + + | 变量 | 类型 | 说明 | + |----------------|--------------------|--------------------------------------| + | .Values.domain | Map | 应用定义的入口地址 URL, 每个 Entry 为：入口名 => URL | + +- 存储信息 + | 变量 | 类型 | 说明 | + | -------------- | ------------------ | ---------------------------------------------------- | + | .Values.userspace.appData | String | 应用可用的集群存储地址 | + | .Values.userspace.appCache | String | 应用可用的本地节点缓存地址 | + | .Values.userspace.userData | String | 用户的数据存储目录 | + +- 集群信息 + | 变量 | 类型 | 说明 | + | -------------- | ------------------ | ---------------------------------------------------- | + | .Values.cluster.arch | String | 集群 CPU 架构 | + + 目前不支持多平台（AMD64 和 ARM）集群。 + +- 应用依赖 + | 变量 | 类型 | 说明 | + | -------------- | ------------------ | ---------------------------------------------------- | + | .Values.deps | Map | 应用所依赖的应用当前的地址和端口 | + | .Values.svcs | Map | 应用所依赖的应用其他 service 和端口 | + + 当应用程序设置对另一个应用程序的依赖关系时，这将通过 `deps` 参数传递。例如，如果一个应用程序设置了对另一个名为“A-Server”的应用程序的依赖关系，并且 A-Server 将条目名称设置为条目主机的 aserver 配置为 `'aserver-svc'`，值将类似于： +``` + { + "aserver_host": "aserver-svc.", + "aserver_port": 80 + } + ``` + 同时，`svcs`会传入 A-Server 的所有 service + ``` + { + "aserver-svc_host": "aserver-svc.", + "aserver-svc_port": [80] # 如果 service 有多个端口会一起传入 + } + ``` + +- 数据库信息 + + | 变量 | 类型 | 说明 | + |----------------------------|--------------------|------------------------------------------------------------------------------------| + | .Values.postgres.host | String | PostgreSQL 数据库地址 | + | .Values.postgres.port | Number | PostgreSQL 数据库端口 | + | .Values.postgres.username | String | PostgreSQL 数据库用户名 | + | .Values.postgres.password | String | PostgreSQL 数据库密码 | + | .Values.postgres.databases | Map | PostgreSQL 数据库名称，以申请数据库名作为 key，例如， 申请 app_db, 变量为.Values.postgres.databases.app_db | + | .Values.mongo.host | String | MongoDB 数据库地址 | + | .Values.mongo.port | Number | MongoDB 数据库端口 | + | .Values.mongo.username | String | MongoDB 数据库用户名 | + | .Values.mongo.password | String | MongoDB 数据库密码 | + | .Values.mongo.databases | Map | MongoDB 数据库名称，以申请数据库名作为 key，例如， 申请 app_db, 变量为.Values.mongo.databases.app_db | + | .Values.redis.host | String | Redis 数据库地址 | + | .Values.redis.port | Number | Redis 数据库端口 | + | .Values.redis.password | String | Redis 数据库密码 | + | .Values.redis.namespaces | Map | Redis 命名空间名称，以申请命名空间作为 key，例如， 申请 app_ns, 变量为.Values.redis.namespaces.app_ns | \ No newline at end of file diff --git a/docs/zh/developer/develop/package/manifest.md b/docs/zh/developer/develop/package/manifest.md new file mode 100644 index 000000000..2dfdeb92e --- /dev/null +++ b/docs/zh/developer/develop/package/manifest.md @@ -0,0 +1,805 @@ +--- +outline: [2, 3] +--- + +# OlaresManifest 规范 + +每一个 Olares 应用的 Chart 根目录下都必须有一个名为 `OlaresManifest.yaml` 的文件。`OlaresManifest.yaml` 描述了一个 Olares 应用的所有基本信息。Olares 应用市场协议和 Olares 系统依赖这些关键信息来正确分发和安装应用。 + +:::info 提示 +最新的 Olares 系统使用的 Manifest 版本为: `0.9.0` +- 在 `options` 中增加 `conflict` 字段, 用于声明不兼容的应用 +- 移除 `options` 中 `analytics` 配置项 +- 修改 `tailscale` 字段的配置格式 +- 增加 `allowedOutboundPorts` 配置，允许通过指定端口进行非 HTTP 协议的对外访问 +- 修改 `ports` 部分的配置 + +::: +:::details Changelog +`0.8.3` +- 在 `dependencies` 配置项里增加 `mandatory` 字段以表示该依赖应用必须安装。 +- 增加 `tailscaleAcls` 配置项，允许 Tailscale 为应用开放指定端口 + +`0.8.2` +- 添加 `runAsUser` 选项，用于限制应用程序在非root权限的用户下运行 + +`0.8.1` +- 添加 `ports` 选项以指定 UDP 或 TCP 的暴露端口 + +`0.7.1` +- 添加新的 `authLevel` 值 `internal` +- 将 `spec`>`language` 改为 `spec`>`locale` 并支持 i18n + ::: + +一个 `OlaresManifest.yaml` 文件的示例如下： + +::: details `OlaresManifest.yaml` 示例 + +```Yaml +olaresManifest.version: '0.8.0' +olaresManifest.type: app +metadata: + name: helloworld + title: Hello World + description: app helloworld + icon: https://file.bttcdn.com/appstore/default/defaulticon.webp + version: 0.0.1 + categories: + - Utilities +entrances: +- name: helloworld + port: 8080 + title: Hello World + host: helloworld + icon: https://file.bttcdn.com/appstore/default/defaulticon.webp + authLevel: private +permission: + appCache: true + appData: true + userData: + - Home/Documents/ + - Home/Pictures/ + - Home/Downloads/BTDownloads/ +spec: + versionName: '0.0.1' + featuredImage: https://link.to/featured_image.webp + promoteImage: + - https://link.to/promote_image1.webp + - https://link.to/promote_image2.webp + fullDescription: | + A full description of your app. + upgradeDescription: | + Describe what is new in this upgraded version. + developer: Developer's Name + website: https://link.to.your.website + sourceCode: https://link.to.sourceCode + submitter: Submitter's Name + language: + - en + doc: https://link.to.documents + supportArch: + - amd64 + limitedCpu: 1000m + limitedMemory: 1000Mi + requiredCpu: 50m + requiredDisk: 50Mi + requiredMemory: 12Mi + +options: + dependencies: + - name: olares + type: system + version: '>=0.1.0' +``` +::: + +## olaresManifest.type + +- 类型：`string` +- 有效值： `app`、`recommend`、`middleware` + +Olares 市场目前支持 3 种类型的应用，各自对应不同场景。本文档以 “app” 为例来解释各个字段。其他类型请参考相应的配置指南。 +- [推荐算法配置指南](recommend.md) + +:::info 示例 +```Yaml +olaresManifest.type: app +``` +::: + +## olaresManifest.version + +- 类型：`string` + +随着 Olares 更新，`OlaresManifest.yaml` 的配置规范可能会发生变化。你可以通过检查 `olaresManifest.version` 来确定这些更改是否会影响你的应用程序。 `olaresManifest.version` 由三个用英文句点分隔的整数组成。 + +- 第 1 位数字增加意味着引入了不兼容的配置项，未升级对应 `OlaresManifest.yaml` 的应用将无法分发或安装。 +- 第 2 位数字增加意味着分发和安装必须字段存在变化，但 Olares 系统仍兼容之前所有版本配置的应用分发与安装。我们建议开发者尽快更新升级应用的 `OlaresManifest.yaml` 文件。 +- 第 3 位数字的改变，不影响应用分发和安装。 + +开发者可以使用 1-3 位的版本号来标识该应用遵循的配置版本。以下是有效版本的一些示例： +```Yaml +OlaresManifest.yaml.version: 1 +OlaresManifest.yaml.version: 1.1.0 +OlaresManifest.yaml.version: '2.2' +OlaresManifest.yaml.version: "3.0.122" +``` + +## Metadata + +应用的基本信息，用于在 Olares 系统和应用市场中展示应用。 + +:::info 示例 +```Yaml +metadata: + name: nextcloud + title: Nextcloud + description: The productivity platform that keeps you in control + icon: https://file.bttcdn.com/appstore/nextcloud/icon.png + version: 0.0.2 + categories: + - Utilities + - Productivity +``` +::: + +### name + +- 类型：`string` +- Accepted Value: `[a-z][a-z0-9]?` + +Olares 中的应用的命名空间，仅限小写字母数字字符。最多 30 个字符，需要与 `Chart.yaml` 中的 `FolderName` 和 `name` 字段保持一致。 + +### title + +- 类型：`string` + +在应用市场中显示的应用标题。长度不超过 `30` 个字符。 + +### description + +- 类型：`string` + +Olares 应用市场中的应用名称下方显示的简短说明。 + +### icon + +- 类型：`url` + +应用图标。 + +图标必须是 `PNG` 或 `WEBP` 格式文件，最大为 `512 KB`，尺寸为 `256x256 px`。 + +### version + +- 类型：`string` + +应用的 Chart Version，每次改变 Chart 目录里的内容时应递增。需遵循[语义化版本规范](https://semver.org/)，需要与 `Chart.yaml` 中的 `version` 字段一致。 + +### categories + +- 类型： `list` +- 有效值： `Blockchain`、`Utilities`、`Social Network`、`Entertainment`、`Productivity` + +在应用市场的哪个类别下展示应用。 + +## Entrances + +指定此应用访问入口的数量。每个应用允许最少 1 个，最多 10 个入口 。 + +:::info 示例 +```Yaml +entrances: +- name: a + host: firefox + port: 3000 + title: Firefox + authLevel: public + invisible: false +- name: b + host: firefox + port: 3001 + title: admin +``` +::: + +### name + +- 类型：`string` +- Accepted Value: `[a-z]([-a-z0-9]*[a-z0-9])?` + + 入口的名称，长度不超过 `63` 个字符。一个应用内不能重复。 + +### port + +- 类型： `int` +- 有效值： `0-65535` + +### host + +- 类型：`string` +- 有效值： `[a-z]([-a-z0-9]*[a-z0-9])?` + + 当前入口的 Ingress 名称，只包含小写字母和数字和中划线`-`，长度不超过 63 个字符。 + +### title + +- 类型：`string` + +安装后 Olares 桌面的显示名称。长度不超过 `30` 个字符。 + +### icon + +- 类型： `url` +- 可选 + +应用安装后 Olares 桌面上的图标。图片文件必须是 `PNG` 或 `WEBP` 格式，不超过 `512 KB`，尺寸为 `256x256 px`。 + +### authLevel + +- 类型：`string` +- 有效值： `public`, `private`, `internal` +- 默认值： `private` +- 可选 + +指定入口的认证级别。 +- **Public**：互联网上的任何人都可以不受限制地访问。 +- **Private**：需要从内部和外部网络访问的授权。 +- **Internal**：需要授权才能从外部网络访问。从内部网络（通过 LAN/VPN）访问时不需要身份验证。 + +### invisible + +- 类型： `boolean` +- 默认值：`false` +- 可选 + +当 `invisible` 为` true` 时，该入口不会显示在 Olares 桌面上。 + +### openMethod + +- 类型：`string` +- 有效值： `default`, `iframe`, `window` +- 默认值： `default` +- 可选 + +指定该入口在桌面的打开方式。 + +`iframe` 代表在桌面的窗口内通过 iframe 新建一个窗口，`window` 代表在浏览器新的 Tab 页打开。`default` 代表跟随系统的默认选择，系统默认的选择是`iframe`。 + +### windowPushState +- 类型： `boolean` +- 默认值：`false` +- 可选 + +将应用嵌入到桌面上的 iframe 中时，应用的 URL 可能会动态更改。由于浏览器的同源策略，桌面（父窗口）无法直接检测到 iframe URL 中的这些变化。因此，如果你重新打开应用程序选项卡，它将显示初始 URL，而不是更新后的 URL。 + +为了确保无缝的用户体验，你可以通过将其设置为 true 来启用此选项。此操作会提示网关自动将以下代码注入到 iframe 中。每当 iframe 的 URL 发生更改时，此代码都会向父窗口（桌面）发送一个事件。因此，桌面可以跟踪 URL 更改并打开正确的页面。 + +::: details 代码 +```Javascript + +``` +::: + +## Ports + +定义暴露的端口 + +:::info 示例 +```Yaml +ports: +- name: rdp-tcp # 提供服务的入口名称 + host: windows-svc # 提供服务的 Ingress 主机名称 + port: 3389 # 提供服务的端口号 + exposePort: 46879 # 暴露的接口，在集群内一次只能分配给一个应用程序。 + addToTailscaleAcl: true # 自动添加到 Tailscle 的 ACL 列表中 +``` +::: + +Olares 会为你的应用暴露指定的端口，这些端口可通过应用域名在本地网络下访问，如`84864c1f.your_olares_id.olares.com:46879`。对于每个公开的端口，Olares 会自动配置相同端口号的 TCP 和 UDP。 + +当设置 `addToTailscaleAcl` 字段为 `true`时，该端口会自动增加tailscale acl中，无需再去tailscale部分配置 + + +:::info 提示 +暴露的端口只能通过本地网络或 Olares 专用网络访问。 +::: + + +## Permission + +:::info 示例 +```Yaml +permission: + appCache: true + appData: true + userData: + - /Home/ + sysData: + - dataType: legacy_prowlarr + appName: prowlarr + port: 9696 + group: api.prowlarr + version: v2 + ops: + - All +``` +::: + +### appCache + +- 类型： `boolean` +- 可选 + +是否需要在 `Cache` 目录创建应用的目录。如需要在部署 yaml 文件中使用`.Values.userspace.appCache`, `appCache` 必须设为 `true`。 + +### appData + +- 类型： `boolean` +- 可选 + +是否需要在 `Data` 目录创建应用的目录。如需要在部署 yaml 中使用`.Values.userspace.appData`, `appData` 必须设为 `true`。 + +### userData + +- 类型：`string` +- 可选 + +应用是否需要对用户的 `Home` 文件夹进行读写权限。列出应用需要访问的用户 `Home` 下的所有目录。部署 YAML 中配置的所有 `userData` 目录都必须包含在此处。 + +### sysData + +- 类型：`list` +- 可选 + +声明该应用程序需要访问的 API 列表。 + +:::info 示例 +```Yaml + sysData: + - group: service.bfl + dataType: app + version: v1 + ops: + - InstallDevApp + - dataType: legacy_prowlarr + appName: prowlarr + port: 9696 + group: api.prowlarr + version: v2 + ops: + - All +``` +::: + +所有系统 API [providers](../advanced/provider.md) 如下： +| Group | version | dataType | ops | +| ----------- | ----------- | ----------- | ----------- | +| service.appstore | v1 | app | InstallDevApp, UninstallDevApp +| message-disptahcer.system-server | v1 | event | Create, List +| service.desktop | v1 | ai_message | AIMessage +| service.did | v1 | did | ResolveByDID, ResolveByName, Verify +| api.intent | v1 | legacy_api | POST +| service.intent | v1 | intent | RegisterIntentFilter, UnregisterIntentFilter, SendIntent, QueryIntent, ListDefaultChoice, CreateDefaultChoice, RemoveDefaultChoice, ReplaceDefaultChoice +| service.message | v1 | message | GetContactLogs, GetMessages, Message +| service.notification | v1 | message | Create +| service.notification | v1 | token | Create +| service.search | v1 | search | Input, Delete, InputRSS, DeleteRSS, QueryRSS, QuestionAI +| secret.infisical | v1 | secret | CreateSecret, RetrieveSecret +| secret.vault | v1 | key | List, Info, Sign + +## Tailscale +- 类型：`map` +- 可选 + +允许应用在 Tailscale 的ACL(Access Control Lists)中开放指定端口。 + +:::info 示例 +```Yaml +tailscale: + acls: + - proto: tcp + dst: + - "*:46879" + - proto: "" # 可选, 如果未指定，则允许使用所有支持的协议 + dst: + - "*:4557" +``` +::: + +## Spec +记录额外的应用信息，主要用于应用商店的展示。 + +:::info 示例 +```Yaml +spec: + namespace: os-system + # 可选。将应用安装到指定的命名空间，如 os-system、user-space 和 user-system + + versionName: '10.8.11' + ## 此 Chart 包含的应用程序的版本。建议将版本号括在引号中。该值对应于 Chart.yaml 文件中的 appVersion 字段。请注意，它与 version 字段无关。 + + featuredImage: https://file.bttcdn.com/appstore/jellyfin/promote_image_1.jpg + # 当应用在应用市场上推荐时，会显示特色图像。 + + promoteImage: + - https://file.bttcdn.com/appstore/jellyfin/promote_image_1.jpg + - https://file.bttcdn.com/appstore/jellyfin/promote_image_2.jpg + - https://file.bttcdn.com/appstore/jellyfin/promote_image_3.jpg + fullDescription: | + Jellyfin is the volunteer-built media solution that puts you in control of your media. Stream to any device from your own server, with no strings attached. Your media, your server, your way. + upgradeDescription: | + upgrade descriptions + developer: Jellyfin + website: https://jellyfin.org/ + doc: https://jellyfin.org/docs/ + sourceCode: https://github.com/jellyfin/jellyfin + submitter: Olares + locale: + - en-US + - zh-CN + # 列出该应用支持的语言和地区 + + requiredMemory: 256Mi + requiredDisk: 128Mi + requiredCpu: 0.5 + # 指定安装和运行应用所需的最少资源。安装应用后，系统将保留这些资源以确保最佳性能。 + + limitedDisk: 256Mi + limitedCpu: 1 + limitedMemory: 512Mi + # 指定应用的最大资源限制。如果应用超出这些限制，它将暂时暂停，以防止系统过载并确保稳定性。 + + legal: + - text: Community Standards + url: https://jellyfin.org/docs/general/community-standards/ + - text: Security policy + url: https://github.com/jellyfin/jellyfin/security/policy + license: + - text: GPL-2.0 + url: https://github.com/jellyfin/jellyfin/blob/master/LICENSE + supportClient: + - android: https://play.google.com/store/apps/details?id=org.jellyfin.mobile + - ios: https://apps.apple.com/us/app/jellyfin-mobile/id1480192618 +``` +::: + +### i18n + +要在 Olares 应用市场中为应用添加多语言支持： + +1. 在 Olares Application Chart 根目录中创建一个 `i18n` 文件夹。 +2. 在 `i18n` 文件夹中，为每个支持的语言环境创建单独的子目录。 +3. 在每个语言环境子目录中，放置 `OlaresManifest.yaml` 文件的本地化版本。 + +Olares 应用市场将根据用户的区域设置自动显示相应的 `OlaresManifest.yaml` 文件的内容。 +:::info 示例 +``` +. +├── Chart.yaml +├── README.md +├── OlaresManifest.yaml +├── i18n +│ ├── en-US +│ │ └── OlaresManifest.yaml +│ └── zh-CN +│ └── OlaresManifest.yaml +├── owners +├── templates +│ └── deployment.yaml +└── values.yaml +``` +::: +目前，你可以为以下字段添加 i18n 内容： +```Yaml +metadata: + description: + title: +spec: + fullDescription: + upgradeDescription: +``` + +### supportArch +- 类型: `list` +- 有效值: `amd64`, `arm64` +- 可选 + +该字段用于声明应用程序支持的 CPU 架构。目前仅支持 `amd64` 和 `arm64` 两种类型。 + +:::info 示例 +```yaml +spec: + supportArch: + - amd64 + - arm64 +``` +::: + +:::info 提示 +Olares 目前不支持混合架构的集群。 +::: + +### onlyAdmin +- 类型: `boolean` +- 默认值: `false` +- 可选 + +设置为 `true` 时，只有管理员可以安装此应用程序。 + +### runAsUser +- 类型: `boolean` +- 可选 + +当设置为 `true` 时，Olares 会强制以用户 ID “1000”（非 root 用户）运行应用程序。 + +## Middleware +- 类型：`map` +- 可选 + +系统提供了高可用的中间件服务，开发者无需重复安装中间件，只需在此填写对应的中间件信息即可，然后可以直接使用应用程序的 deployment YAML 文件中相应的中间件信息。 + +使用 `scripts` 字段指定创建数据库后应执行的脚本。此外，使用 `extension` 字段在数据库中添加相应的扩展名。 + +:::info 示例 +```Yaml +middleware: + postgres: + username: immich + databases: + - name: immich + extensions: + - vectors + - earthdistance + scripts: + - BEGIN; + - ALTER DATABASE $databasename SET search_path TO "$user", public, vectors; + - ALTER SCHEMA vectors OWNER TO $dbusername; + - COMMIT; + # 操作系统提供了两个变量 $databasename 和 $dbusername，命令执行时会被 Olares 应用运行时替换。 + redis: + password: password + namespace: db0 + mongodb: + username: chromium + databases: + - name: chromium + script: + - 'db.getSiblingDB("$databasename").myCollection.insertOne({ x: 111 });' + # 请确保每一行都是完整的查询。 +``` +::: + +使用 deployment YAML 中的中间件信息： + +```yaml +- name: DB_POSTGRESDB_DATABASE # 你在 OlaresManifest 中配置的数据库名称，在 middleware.postgres.databases[i].name 中指定 + value: {{ .Values.postgres.databases. }} +- name: DB_POSTGRESDB_HOST + value: {{ .Values.postgres.host }} +- name: DB_POSTGRESDB_PORT + value: "{{ .Values.postgres.port }}" +- name: DB_POSTGRESDB_USER + value: {{ .Values.postgres.username }} +- name: DB_POSTGRESDB_PASSWORD + value: {{ .Values.postgres.password }} + + +# 对于mongodb来说，对应的值如下 +host --> {{ .Values.mongodb.host }} +port --> "{{ .Values.mongodb.port }}" # yaml 文件中的端口和密码需要用双引号括起来。 +username --> {{ .Values.mongodb.username }} +password --> "{{ .Values.mongodb.password }}" # yaml 文件中的端口和密码需要用双引号括起来。 +databases --> "{{ .Values.mongodb.databases }}" # 数据库的值类型是 map。你可以使用 {{ .Values.mongodb.databases. }} 获取数据库。 是你在 OlaresManifest 中配置的名称，在 middleware.mongodb.databases[i].name 中指定 + + +# 对于Redis来说，对应的值如下 +host --> {{ .Values.redis.host }}For Redis, the corresponding value is as follow +port --> "{{ .Values.redis.port }}" +password --> "{{ .Values.redis.password }}" + +``` + +## Options + +在此部分配置系统相关的选项。 + +### policies +- 类型：`map` +- 可选 + +定义应用子域的详细访问控制。 + +:::info 示例 +```yaml +options: + policies: + - uriRegex: /$ + level: two_factor + oneTime: false + validDuration: 3600s + entranceName: gitlab +``` +::: + +### clusterScoped +- 类型：`map` +- 可选 + +是否为 Olares 集群中的所有用户安装此应用程序。 + +:::info 服务端示例 +```yaml +metadata: + name: gitlab +options: + appScope: + clusterScoped: true + appRef: + - gitlabclienta # 客户端的应用名称 + - gitlabclientb +``` +::: + +:::info 客户端示例 +```yaml +metadata: + name: gitlabclienta +options: + dependencies: + - name: olares + version: ">=0.3.6-0" + type: system + - name: gitlab # 服务器端的应用名称 + version: ">=0.0.1" + type: application + mandatory: true +``` +::: + +### dependencies +- 类型：`list` + +如果此应用依赖于其他应用或需要特定操作系统版本，请在此处声明。 + +如果此应用程序需要依赖其他应用程序才能正确安装，则应将 `mandatory` 字段设置为 `true`。 + +:::info 示例 +```yaml +options: + dependencies: + - name: olares + version: ">=1.0.0-0" + type: system + - name: mongodb + version: ">=6.0.0-0" + type: middleware + mandatory: true # 如果必须先安装此依赖，请将此字段设为 true。 +``` +::: + +### websocket +- 类型：`map` +- 可选 + +为应用启用 websocket。请参阅 [websocket](../advanced/websocket.md) 了解更多信息。 + +:::info 示例 +```yaml +options: + websocket: + url: /ws/message + port: 8888 +``` +::: + +### resetCookie +- 类型：`map` +- 可选 + +如果应用需要 cookie，请启用此功能。更多信息请参考 [cookie](../advanced/cookie.md)。 + +:::info 示例 +```yaml +options: + resetCookie: + enabled: true +``` +::: + +### upload +- 类型： `map` +- 可选 + +Olares 应用运行时包含一个内置文件上传组件，旨在简化应用程序中的文件上传过程。请参阅 [上传](../advanced/file-upload.md) 了解更多信息。 + +:::info Example +```yaml +upload: + # 允许上传的文件类型，*为任意类型， 上传时会指定 file_type，必须在允许的文件类型中 + fileType: + - pdf + # dest 的路径必须为某一个 mountPath + dest: /appdata + # 文件上传的最大大小，单位为字节 + limitedSize: 3729747942 +``` +::: + +### mobileSupported +- 类型： `boolean` +- 默认值： `false` +- 可选 + +确定应用是否与移动网络浏览器兼容并且可以在移动版本的 Olares 桌面上显示。如果应用程序针对移动网络浏览器进行了优化，请启用此选项。这将使该应用程序在移动版 Olares 桌面上可见并可访问。 + +:::info 示例 +```yaml +mobileSupported: true +``` +::: + +### oidc +- 类型：`map` +- 可选 + +Olares 包含内置的 OpenID Connect 身份验证组件，以简化用户的身份验证。启用此选项可在你的应用中使用 OpenID。 +```yaml +# yaml 中 OpenID 相关变量 +{{ .Values.oidc.client.id }} +{{ .Values.oidc.client.secret }} +{{ .Values.oidc.issuer }} +``` + +:::info 示例 +```yaml +oidc: + enabled: true + redirectUri: /path/to/uri + entranceName: navidrome +``` +::: + +### apiTimeout +- 类型：`int` +- 可选 + +指定 API 提供程序的超时限制（以秒为单位）。默认值为 `15`。使用 `0` 允许无限制的 API 连接。 + +:::info 示例 +```yaml +apiTimeout: 0 +``` +::: + +### allowedOutboundPorts +- 类型： `map` +- 可选 + +要求开通以下端口进行非 HTTP 协议的对外访问，例如 SMTP 服务等。 + +:::info 示例 +```yaml +allowedOutboundPorts: + - 465 + - 587 +``` +::: \ No newline at end of file diff --git a/docs/zh/developer/develop/package/recommend.md b/docs/zh/developer/develop/package/recommend.md new file mode 100644 index 000000000..7c3ad8a1c --- /dev/null +++ b/docs/zh/developer/develop/package/recommend.md @@ -0,0 +1,320 @@ +# 推荐算法配置指导 + +为 `recommend` 创建应用程序图表时，主要需要配置位于 `templates/` 文件夹中的四个文件：`embedding.yaml` 、`prerank.yaml` 、`rank.yaml` 和 `train.yaml`。 + + +## embedding.yaml + +::: details embedding.yaml 示例 + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: user-embedding-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '0 */1 * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Replace + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: userEmbeddingFlow + volumes: + - name: huggingface + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/model/huggingface + templates: + - name: userEmbeddingFlow + steps: + - - name: user-embedding + template: user-embedding-template + - name: user-embedding-template + container: + image: 'beclab/r4userembedding' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /root/.cache/huggingface + name: huggingface +``` + +::: + +### 字段介绍 + +| 选项名称 | 描述 | +| -------------------------- | ------------------------------------------------------------------------------------------ | +| apiVersion | 使用的API版本。 | +| kind | 定义了一个CronWorkflow对象。 | +| metadata.name | CronWorkflow的名称。 | +| metadata.namespace | CronWorkflow所属的命名空间。 | +| spec.schedule | Cron表达式，定义了CronWorkflow的调度时间。 | +| spec.startingDeadlineSeconds | CronWorkflow的启动截止时间，表示从调度时间开始的最大延迟时间。 | +| spec.concurrencyPolicy | 并发策略，指定了当CronWorkflow下一次调度时间到来时，如何处理当前正在运行的作业。 | +| spec.successfulJobsHistoryLimit | 成功作业的历史记录限制数。 | +| spec.failedJobsHistoryLimit | 失败作业的历史记录限制数。 | +| spec.suspend | 指示是否暂停CronWorkflow的运行。 | +| spec.ttlStrategy.secondsAfterSuccess | 成功作业完成后的存活时间，以秒为单位。 | +| spec.ttlStrategy.secondsAfterCompletion | 作业完成后的存活时间，以秒为单位。 | +| spec.ttlStrategy.secondsAfterFailure | 失败作业完成后的存活时间，以秒为单位。 | +| spec.workflowSpec.entrypoint | Workflow的入口点。 | +| spec.workflowSpec.volumes[0].name | 卷的定义，名称为huggingface。 | +| spec.workflowSpec.volumes[0].hostPath.type | 宿主机路径类型，指定为目录或创建目录。 | +| spec.workflowSpec.volumes[0].hostPath.path | 宿主机路径。 | +| spec.workflowSpec.templates[0].name | Workflow模板的名称。 | +| spec.workflowSpec.templates[0].steps[0][0].name | 步骤的定义，名称。 | +| spec.workflowSpec.templates[0].steps[0][0].template | 引用的模板名称。 | +| spec.workflowSpec.templates[1].name | 模板的名称。 | +| spec.workflowSpec.templates[1].container.image | 容器的镜像名称。 | +| spec.workflowSpec.templates[1].container.imagePullPolicy | 镜像拉取策略。 | +| spec.workflowSpec.templates[1].container.env[0].name | 环境变量的定义，名称。 | +| spec.workflowSpec.templates[1].container.env[0].value | 环境变量的值。 | +| spec.workflowSpec.templates[1].container.env[1].name | 环境变量的定义，名称。 | +| spec.workflowSpec.templates[1].container.env[1].value | 环境变量的值。 | +| spec.workflowSpec.templates[1].container.volumeMounts[0].mountPath | 挂载路径的定义。 | +| spec.workflowSpec.templates[1].container.volumeMounts[0].name | 挂载的卷名称。 | + +## prerank.yaml + +::: details prerank.yaml 示例 + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: prerank-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '*/5 * * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Replace + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: algorithm + volumes: + - name: nfs + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/data + - name: juicefs + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/data + templates: + - name: algorithm + steps: + - - name: recall + template: recall-template + - - name: prerank + template: prerank-template + - name: recall-template + container: + image: 'beclab/r4recall:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: NFS_ROOT_DIRECTORY + value: /nfs + - name: JUICEFS_ROOT_DIRECTORY + value: /juicefs + - name: ALGORITHM_FILE_CONFIG_PATH + value: /usr/config/ + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + - name: SUPPORT_LANGUAGE + value: en + - name: SUPPORT_TIMELINESS + value: '0' + - name: SYNC_PROVIDER + value: bytetrade + - name: SYNC_FEED_NAME + value: sport + - name: SYNC_MODEL_NAME + value: bert_v2 + volumeMounts: + - mountPath: /nfs + name: nfs + - mountPath: /juicefs + name: juicefs + - name: prerank-template + container: + image: 'beclab/r4prerank:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: NFS_ROOT_DIRECTORY + value: /nfs + - name: JUICEFS_ROOT_DIRECTORY + value: /juicefs + - name: ALGORITHM_FILE_CONFIG_PATH + value: /usr/config/ + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + - name: SUPPORT_LANGUAGE + value: en + - name: SUPPORT_TIMELINESS + value: '0' + volumeMounts: + - mountPath: /nfs + name: nfs + - mountPath: /juicefs + name: juicefs + +``` + +::: + + +## rank.yaml + +::: details rank.yaml 示例 + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: rank-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '*/5 * * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Forbid + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: rankFlow + volumes: + - name: model + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/model + templates: + - name: rankFlow + steps: + - - name: extractor + template: extractor-template + - - name: rank + template: rank-template + - name: extractor-template + container: + image: 'beclab/r4extractor:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + - name: rank-template + container: + image: 'beclab/r4rank' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + + +``` + +::: + + +## train.yaml + +::: details train.yaml 示例 + +```Yaml +apiVersion: argoproj.io/v1alpha1 +kind: CronWorkflow +metadata: + name: rank-r4sport + namespace: {{ .Release.Namespace }} +spec: + schedule: '*/5 * * * *' + startingDeadlineSeconds: 0 + concurrencyPolicy: Forbid + successfulJobsHistoryLimit: 1 + failedJobsHistoryLimit: 1 + suspend: false + ttlStrategy: + secondsAfterSuccess: 3600 + secondsAfterCompletion: 3600 + secondsAfterFailure: 3600 + workflowSpec: + entrypoint: rankFlow + volumes: + - name: model + hostPath: + type: DirectoryOrCreate + path: >- + {{ .Values.userspace.appData }}/rss/model + templates: + - name: rankFlow + steps: + - - name: extractor + template: extractor-template + - - name: rank + template: rank-template + - name: extractor-template + container: + image: 'beclab/r4extractor:v0.0.5' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + - name: rank-template + container: + image: 'beclab/r4rank' + imagePullPolicy: Always + env: + - name: KNOWLEDGE_BASE_API_URL + value: {{ .Values.apiUrl }} + - name: TERMINUS_RECOMMEND_SOURCE_NAME + value: r4sport + volumeMounts: + - mountPath: /opt/rank_model + name: model + +``` +::: \ No newline at end of file diff --git a/docs/zh/developer/develop/submit/index.md b/docs/zh/developer/develop/submit/index.md new file mode 100644 index 000000000..de5a65a2b --- /dev/null +++ b/docs/zh/developer/develop/submit/index.md @@ -0,0 +1,123 @@ +--- +outline: [2, 3] +--- + +# 提交应用 + +## 详细步骤 + +**基本流程** + +1. 在 Olares 上测试你的应用，根据[指南](../package/chart.md)创建 Olares 应用 Chart。 +2. Fork 官方 [Olares 应用市场仓库](https://github.com/beclab/apps)。添加应用 Chart。创建 PR 到 `beclab/apps:main`。 +3. 等待 **GitBot** 检查你的 PR。如果需要，修改 PR 直至通过。 +4. PR 合并后，你的应用程序就可以启动了。 + + +### 1. 创建并测试 Olares 应用 + +在提交应用程序之前，请确保它已在你的 Olares 上经过完整测试。 +- 使用 DevBox 的开发容器在真实的在线环境中测试和调试你的应用。 [了解有关 DevBox 的更多信息](../tutorial/studio)。 +- 使用 Market 应用程序中的[自定义安装](../../../manual/olares/market#install-custom-applications) 进行用户测试。 + +### 2. 提交应用 +应用提交需要通过 **Pull Request** 完成。具体步骤如下： +- 从官方 [Olares 应用市场仓库](https://github.com/beclab/apps)创建 fork，并在你的 fork 仓库中添加应用 Chart。 +- 创建一个指向 `beclab/apps:main` 分支的 Draft PR。 +- 请按照模板要求编辑 PR 标题和内容。 + - **PR 标题**必须符合以下格式：[PR 类型][文件夹名][版本]标题内容 + - `PR 类型`包括： + - NEW: 提交新应用 + - UPDATE: 更新已成功合并的应用 + - REMOVE: 移除已成功合并的应用 + - SUSPEND: 暂停已成功合并的应用在应用商店的分发 + - `文件夹名`是你的 Olares 应用 Chart 名称。必须符合 [chart 规范](../package/chart.md)中的命名要求。 + - `版本`指你的应用 chart 的` Chart 版本`，需要与 `Chart.yaml` 中的 `version` 字段和 `OlaresManifest.yaml` 元数据部分保持一致。 +- 为防止你的 PR 被错误解析或关闭，请遵守以下规则： + - PR 标题只能包含一个 `PR 类型`、`文件夹名`和`版本`。 + - 你的 `PR 类型`必须是预定义类型之一。 + - PR 只能添加或修改PR标题中声明的`文件夹名`下的内容。 + - 同一`文件夹名`同时只能存在一个 Open PR 或 Draft PR。 + - 你必须是要修改的文件夹的所有者之一。所有者列在chart中的`owners`文件中。如果你正在提交新应用，你的 GitHub 用户名应该包含在 `owners` 文件中。 + +- 在 Draft PR阶段，你可以持续调整 PR 内容并添加新的提交。一切就绪后，点击 **Ready for review** 按钮提交 PR 并调用 **GitBot** 进行检查。 + +:::info 注意 +PR 的标题和内容对于 **GitBot** 来说至关重要。请按照模板规范填写。**GitBot** 可能会自动关闭任何无效的PR。 +::: + +### 3. 跟踪 PR 状态 +- 当你的 PR 被标记为 `PR 类型`时，表示你的 PR 标题有效。请**不要在之后修改 `PR 类型`。**如果它不符合你的意图，只需关闭它并创建一个新的。 + +- 你可以通过状态标签跟踪PR的进度： + - `waiting to submit`: 你的 PR 存在问题，需要在合并前进行进一步修改。 + - `closed`: 你的 PR 无效或包含无法纠正的错误。 + - `waiting to merge`: 一切进展顺利。你的PR已通过检查，现在正等待 **GitBot** 自动合并。 + - `merged`: 你的PR已被自动合并到`beclab/apps:main`中。 + +- 如果 **GitBot** 自动关闭了你的 PR，请**不要重新打开**它。这表示 PR 存在不可修复的问题，**GitBot** 不得不终止检查流程。你可以在进行必要修改后提交新的 PR。 + +- 当 PR 处于 `waiting to submit` 状态时，你可以继续提交 Commits 来修改你的 PR。提交 Commit 后，GitBot将重新检查你提交的应用 chart 文件并更新 PR 状态。 + +- 一旦你的 PR 通过所有检查，它将自动合并到 `beclab/apps:main` 中。应用将在一段时间后在**Olares Market**上列出。 + +- 如果你在提交过程中遇到任何问题，随时可以联系 Olares 团队或寻求社区帮助。 + +## 管理你的应用 + +你可以通过创建 Pull Request 到 `beclab/apps:main` 继续管理和维护你的应用。你可以升级应用、修改其可用性，或从**Olares Market**完全移除它。 + +管理应用的流程与提交类似。你创建特定类型的 Pull Request，GitBot 会处理剩余工作。Olares 使用应用 chart 根目录中的**特殊控制文件**来管理应用状态。这些**特殊控制文件**是带有特定后缀的空文件，如 `.suspend` 和 `.remove`。 + +:::info 注意 +初次提交时不应包含 ".suspend" 或 ".remove" 文件。 +::: + +### 更新 +当你需要更新已发布的应用时，你需要创建一个 `UPDATE` PR。 + +**请注意：** +- 每当你对应用chart进行更改时，如升级程序、更新元数据或更改所有者列表，请务必升级你的chart版本。 +- 更新后的应用chart版本必须***大于***仓库中的当前版本。 +- 更新的应用chart根目录中不包含 `.suspend` 或 `.remove` 文件。 +- **Olares 应用市场**不提供版本回滚。如果你的应用存在任何问题，你需要提交新版本来修复它。 +- 为避免潜在冲突，我们建议同步你的fork并将PR的提交变基到最新的main分支。 + +### 暂停 +如果出于任何原因你想暂时禁用你的应用在**Olares 应用市场**的下载和安装，请提交一个`SUSPEND` PR。 + +**请注意：** +- 提交的应用chart版本必须与仓库中的当前版本***匹配***。 +- 你提交的根目录应包含 `.suspend` 文件，且不应包含 `.remove` 文件。 +- 一旦暂停PR通过检查并合并，应用商店将停止列出你的应用。 +- 已经下载并安装应用的用户在暂停后可以继续使用它。 + +### 移除 +如果出于任何原因你想从**Olares Market**移除你的应用，请提交一个 `REMOVE` PR。 + +**请注意：** +- 完全清空当前应用目录中的文件，并在根目录中添加一个 `.remove` 文件。 +- 一旦移除PR通过检查并合并，应用商店将移除你的应用。 +- 你将无法在未来重用相同的目录或应用chart名称。 +- 已经下载并安装应用的用户在移除后可以继续使用它。 + +## 推广你的应用 + +通过使用组织良好的应用描述、截图和宣传图片来突出显示应用的特点和功能，可以帮助吸引Market中的新用户。截图和预览可以直观地展示用户体验，帮助你的应用脱颖而出。 + +要在应用详情页添加宣传图片，请在 `OlaresManifest.yaml` 文件的 `spec` 部分的 `promoteImage` 字段中包含这些资源的链接。 + +:::info **Olares 应用市场的资源规范** + +- 应用的**图标**必须为 PNG 或 WEBP 格式，大小不超过 512 KB，尺寸为 256x256 像素。 + +- 强烈建议至少上传 2 张**截图**用于推广。**截图**必须为 JPEG、PNG 或 WEBP 格式，每张大小不超过 8MB，尺寸为1440x900像素。你最多可以上传 8 张**截图**。 + +- 如果你希望你的应用在市场中被推荐，则需要一张**特色图片**。在 `OlaresManifest.yaml` 文件的 `spec` 部分的 `featuredImage` 字段中添加此图片的链接。图片必须为 JPEG、PNG 或 WEBP 格式，大小不超过 8MB，尺寸为 1440x900 像素。 + ::: + +## 邀请他人协作 + +有两种方式可以邀请他人一起开发Olares应用： +1. 将其他开发者的 GitHub 用户名添加到 `owners` 文件中。列在`owners`中的每个开发者都可以独立 fork 仓库并提交他们的更改。 +2. 将其他人添加为你 fork 仓库的协作者。在这种情况下，你作为代表创建 Pull Request，所有其他人可以共同提交到计划合并的分支。 diff --git a/docs/zh/developer/develop/tutorial/index.md b/docs/zh/developer/develop/tutorial/index.md new file mode 100644 index 000000000..b93d91d8c --- /dev/null +++ b/docs/zh/developer/develop/tutorial/index.md @@ -0,0 +1,15 @@ +# 教程 + +欢迎阅读 Olares 应用开发指南。这些详细的教程将逐步指导你从零开始构建 Olares 应用。 + +在开始前，你可以先了解一些 Olares 的基本概念，如： +- [Olares 的组成](../../../manual/concepts/architecture.md) +- [Olares 应用 Chart](../../develop/package/chart.md) +- [Olares 在 Helm 上的扩展](../package/extension.md)。 + +这些基础知识将帮助你更有效地掌握的开发流程。 + +你还可以先了解下 [DevBox](studio.md)，这是 Olares 为开发人员构建 Olares 应用程序提供的内置应用程序。 + +如果你是 Olares 开发的新手，想直接开始编码，可以从[创建首个应用](./note/index.md)开始。本教程将指导你构建一个小型笔记应用程序。 + diff --git a/docs/zh/developer/develop/tutorial/note/backend.md b/docs/zh/developer/develop/tutorial/note/backend.md new file mode 100644 index 000000000..f24b7ec94 --- /dev/null +++ b/docs/zh/developer/develop/tutorial/note/backend.md @@ -0,0 +1,71 @@ +# 开始后端程序开发 + +## 克隆代码 + + 打开后端的开发容器 IDE, 打开 Terminal，可控你的代码到 `/Code` 目录。 + + ```sh + gh auth login + + cd /Code + git clone https://github.com/beclab/terminus-app-demo.git + ``` + + 之后便可以在 IDE 中打开后端代码进行开发。 + + ![server IDE](/images/developer/develop/tutorial/backend/dev.jpg) + +## 连接数据库 + + 在开发容器中，可以通过环境变量获取数据库信息（如果你在部署的时候以环境变量的方式将数据库参数注入容器）。 + + 以 gorm 为例： + ```go + import ( + "fmt" + "os" + "strconv" + + "gorm.io/driver/postgres" + "gorm.io/gorm" + ) + + + func init() { + var err error + + db_host = os.Getenv("DB_HOST") + db_port, err = strconv.Atoi(os.Getenv("DB_PORT")) + if err != nil { + panic(err) + } + db_username = os.Getenv("DB_USER") + db_password = os.Getenv("DB_PWD") + db_name = os.Getenv("DB_NAME") + } + + + func main(){ + dsn := fmt.Sprintf("host=%s user=%s password=%s dbname=%s port=%d sslmode=disable TimeZone=Asia/Shanghai", + db_host, db_username, db_password, db_name, db_port) + db, err := gorm.Open(postgres.Open(dsn), &gorm.Config{}) + if err != nil { + panic(err) + } + + } + ``` + +## 调试 + + 完成代码开发后，便可在 IDE 中运行调试你的代码。 + + ![run and debug](/images/developer/develop/tutorial/backend/debug.jpg) + + 也可以在 Terminal 中运行你的代码，例如： + + ```sh + go run main.go + ``` + + 这时，就可以配合前端完成接口联调。 \ No newline at end of file diff --git a/docs/zh/developer/develop/tutorial/note/create.md b/docs/zh/developer/develop/tutorial/note/create.md new file mode 100644 index 000000000..8363dada1 --- /dev/null +++ b/docs/zh/developer/develop/tutorial/note/create.md @@ -0,0 +1,190 @@ +--- +outline: [2, 3] +--- + +# 如何开始开发一个应用 + +## 下载并安装 DevBox + +1. 从 Olares 应用市场安装 [DevBox](https://market.olares.com/app/devbox)。 +2. 在 Olares 桌面的 LaunchPad 中找到 DevBox 图标。 +3. 点击图标启动应用程序。 + + ![main screen](/images/developer/develop/tutorial/create/home.jpg) + +## 创建应用 + +点击 **Create a new application**，从模版创建一个空白的 Olares 应用。 +- 在 **App Name** 一栏，输入你的应用名称。 +- 设置 **App type** 为 **app**。 +- 修改 APP 入口的端口。 +- **Image** 一栏填写应用将要推送的镜像仓库的镜像名称和 tag。 + +![create app](/images/developer/develop/tutorial/create/create.jpg) + +## 设置应用配置 + +创建应用程序后，你可以在 **Files** 选项卡下看到 DevBox 生成的 Olares Application Chart 文件。你可以根据需要添加、删除或重命名各种配置文件。 + +![upload icon](/images/developer/develop/tutorial/create/add-file.jpg) + +### Chart.yaml + +`Chart.yaml `文件是 Helm Chart 规范所必须的文件之一。其中包含了应用的名称和 Chart Version，你可以[在此](https://helm.sh/docs/topics/charts/)了解更多。我们暂时先不用修改默认创建的`Chart.yaml`。 + +### OlaresManifest.yaml +在 `OlaresManifest.yaml` 文件中，你可以更改许多配置。例如： +- 更改应用的标题、图标和其他详细信息 +- 添加系统中间件 +- 获取系统目录访问的权限 +- 更改应用程序的所需的资源限制 + +#### 添加系统的[数据库集群需求](../../package/manifest.md#middleware) + +![config app](/images/developer/develop/tutorial/create/olares-manifest.jpg) + +此处我们需要申请一个 PostgreSQL 的数据库，在配置文件中添加以下内容。 +```Yaml +middleware: + postgres: + username: postgres + databases: + - name: db + distributed: false +``` + +申请时，需要定义你的数据库访问用户名。也可以自定以密码（只需要添加一个 password 申明），也可以由系统生成随机密码。这里需要设置你的 APP 需要的 database name。另外，还可以选择申请一个分布式数据库。如果选在分布式数据库，系统会为你创建一个[citus](https://github.com/citusdata/citus)数据库 + +完成配置后，可在你的 deployment 中引用对应的数据库配置。例如，在容器的环境变量中引用。 +```yaml +- env: + - name: DB_PORT + value: "{{ .Values.postgres.port }}" + - name: DB_NAME + value: "{{ .Values.postgres.databases.demo }}" + - name: DB_USER + value: "{{ .Values.postgres.username }}" + - name: DB_HOST + value: "{{ .Values.postgres.host }}" + - name: DB_PWD + value: "{{ .Values.postgres.password }}" +``` + - `.Values.postgres.username`：对应申请 PostgreSQL 中的 username。 + - `.Values.postgres.databases.demo`：对应申请中的 database name。 + - `.Values.postgres.password`：对应申请中的 password + - `.Values.postgres.host`：系统为 APP 指定的数据库服务地址 + - `.Values.postgres.port`：系统为 APP 指定的数据库服务的端口 + +::: warning +这些参数不应该被硬编码，它们必须引用系统传入的变量，并且系统会随机化配置中的数据库信息。 +::: + +#### 申请系统的[文件系统访问权限](../../package/manifest.md#permission) + +为了能在 Olares 中读取和保存文件，我们需要在 `Permissions` 一项中，配置所需的文件目录。`OlaresManifest.yaml`提供了三个位置的文件目录，分别是： +- `appData`: 申请应用独立数据云存储空间。 +- `appCache`: 给应用申请节点本地磁盘（一般为 SSD 磁盘）数据缓存空间。 +- `userData`: 申请用户的数据目录访问权限。可列举需要访问的目录列表。 + +完成上述配置后，就可以在你的 deployment 中引用这些配置。 + +```yaml +volumes: + - hostPath: + path: "{{ .Values.userspace.appCache }}/demo" + type: DirectoryOrCreate + name: appcache + - hostPath: + path: "{{ .Values.userspace.appData }}/demo" + type: DirectoryOrCreate + name: appdata +``` + - `.Values.userspace.appCache` 对应 appCache 目录 + - `.Values.userspace.appData` 对应 appData 目录 + - `.Values.userspace.userData` 对应 userData 目录 + +### deployment.yaml + +`templates` 文件夹中的 `deployment.yaml` 详细描述了应用的部署配置。 + +如果你的应用分为前后端两个不同的容器。你可以在 templates 的部署文件中，添加多个容器。DevBox 将识别这些不同的容器并将它们分别绑定到不同的开发容器。例如， +```yaml +containers: + # 前端容器 + - env: + - name: PGID + value: "1000" + - name: PUID + value: "1000" + - name: TZ + value: Etc/UTC + image: bytetrade/demo-app:0.0.1 + name: demo + ports: + - containerPort: 8080 + resources: + limits: + cpu: "1" + memory: 2000Mi + requests: + cpu: 50m + memory: 1000Mi + volumeMounts: + - mountPath: /appcache + name: appcache + + # Server 端容器 + - env: + - name: DB_PORT + value: "{{ .Values.postgres.port }}" + - name: DB_NAME + value: "{{ .Values.postgres.databases.demo }}" + - name: DB_USER + value: "{{ .Values.postgres.username }}" + - name: DB_HOST + value: "{{ .Values.postgres.host }}" + - name: DB_PWD + value: "{{ .Values.postgres.password }}" + - name: PGID + value: "1000" + - name: PUID + value: "1000" + - name: TZ + value: Etc/UTC + image: bytetrade/demo-server:0.0.1 + name: server + ports: + - containerPort: 9000 + resources: + limits: + cpu: "1" + memory: 1000Mi + requests: + cpu: 50m + memory: 500Mi + volumeMounts: + - mountPath: /appcache + name: appcache + - mountPath: /appdata + name: appdata +``` + +## 绑定容器 +配置完上述信息后，你需要在 **Containers** 页面为这个开发中的应用，绑定开发容器，进行代码开发。 + +![containers](/images/developer/develop/tutorial/create/bind.jpg) + +你可以为绑定的开发容器设置一个指定的开发环境，目前 DevBox 支持 NodeJS、Golang、python 三种开发容器。让我们给 demo 前端容器绑定一个 NodeJS 开发容器，给 Server 容器绑定一个 Golang 的开发容器。 + +这里选择了创建一个新的开发容器。如果之前已经创建过未绑定的开发容器，这里也可以选择一个已有的容器进行绑定。 + +![bind container](/images/developer/develop/tutorial/create/bind-2.jpg) + +## 安装应用 +完成开发容器绑定后，就可以点击右上角的安装将当前应用安装到系统中了。等待安装状态从 `Processing` 变为 `Running` 即表示应用已安装完成，可进入正式的代码开发流程。 + +![installing](/images/developer/develop/tutorial/create/installing.jpg) + +此时，再次进入 Containers 页面，可以看到开发容器上的 **Open IDE** 按钮激活。点击即可进入开发环境进行代码开发。 + +![processing](/images/developer/develop/tutorial/create/success.jpg) diff --git a/docs/zh/developer/develop/tutorial/note/frontend.md b/docs/zh/developer/develop/tutorial/note/frontend.md new file mode 100644 index 000000000..0ac363c7a --- /dev/null +++ b/docs/zh/developer/develop/tutorial/note/frontend.md @@ -0,0 +1,75 @@ +# 开始前端程序开发 + +## 预览应用 +应用安装完成后，可以通过 DevBox 的**预览**按钮，预览应用的前端效果。 + +![preview](/images/developer/develop/tutorial/frontend/preview.jpg) + +## 打开 IDE + +打开前端的开发容器 IDE, 可以看见开发容器的预览欢迎页。之后的开发流程与[开发后端](backend.md)类似，在 Terminal 中克隆你的前端代码。 + +::: tip +在本教程中，因为前后端共开发容器共享了代码目录，后端 clone 代码后，前端不需要再次克隆代码。 +::: + +克隆完代码后，如果是 Node 项目，可能需要做配置修改。 + +- **Vite 配置修改** + + 如果前端项目采用了 vite，需要增加 hmr 配置。Vite 在 dev 状态，会启动 websocket 监听服务器端发送的代码更新 reload 通知。默认 ws 端口为 server 启动的端口。而 dev app 启动了 nginx 代理，采用了标准的 443 端口。所以需要做相应修改。 + + 按以下方式修改 vite.config.js 文件： + ```js + export default defineConfig({ + server: { + hmr: { + clientPort: 443, + }, + }, + }); + ``` +- **Nginx 配置修改** + + 配置好项目的开发环境后，需要修改 Nginx 配置。打开 `/etc/nginx/conf.d/dev/dev.conf` 修改： + + ```nginx + location / { + proxy_pass http://127.0.0.1:9000; + proxy_set_header Host $http_host; + proxy_set_header X-real-ip $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $http_connection; + proxy_set_header Accept-Encoding gzip; + } + ``` + + 然后重启 Nginx： + ```sh + nginx -s reload + ``` +## 运行开发模式 +完成 Nginx 配置后，你就可以启动你的前端程序的开发模式，并在 Olares 中预览你的应用： + +```sh +npm run dev +``` + +![frontend preview](/images/developer/develop/tutorial/frontend/preview2.jpg) + +如果你需要为前端设置后端 API 代理，可以在 Nginx 中修改代理配置 + + ```nginx + location /api/ { + proxy_pass http://127.0.0.1:9001; + proxy_set_header Host $http_host; + proxy_set_header X-real-ip $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection $http_connection; + proxy_set_header Accept-Encoding gzip; + } + ``` diff --git a/docs/zh/developer/develop/tutorial/note/index.md b/docs/zh/developer/develop/tutorial/note/index.md new file mode 100644 index 000000000..c480983e9 --- /dev/null +++ b/docs/zh/developer/develop/tutorial/note/index.md @@ -0,0 +1,16 @@ +# 创建你的首个 Olares 应用 + +你可以通过本教程学习如何使用 DevBox 开发一个 Olares 应用。 + +整个教程以开发一个简单的 [Note](https://github.com/beclab/terminus-app-demo) 工具为例。展示如何从创建应用开始，开发一个完整的 Olares 应用。 + +整个教程分为以下3个部分： + +1. [创建应用](./create.md)
+ 展示如何创建一个 Olares 应用，并逐步配置这个应用的初始化开发环境。 + +2. [开发后端](./backend.md)
+ 学习如何利用 DevBox 的 IDE 完成后端 Golang 程序的开发，并为前端提供 API 接口。 + +3. [开发前端](./frontend.md)
+ 以 NodeJS 为例，学习如何在 DevBox 的提供的 IDE 中开始前端页面的相关开发。 diff --git a/docs/zh/developer/develop/tutorial/studio.md b/docs/zh/developer/develop/tutorial/studio.md new file mode 100644 index 000000000..bf7d6eaeb --- /dev/null +++ b/docs/zh/developer/develop/tutorial/studio.md @@ -0,0 +1,13 @@ +# 了解 DevBox + +在 Olares 中，我们为每个开发者提供了一个为 Olares 开发应用的开发工具，这就是 DevBox。 + +- 开发者为什么需要 DevBox 呢？ + + Olares 作为一个具有诸多云原生特性的系统，有大量的系统上下文环境在开发者的单机开发环境很难模拟。同时，Olares 独有的沙盒体系也需要在真实的系统环境中才能完成 End to End 的测试。所以，为了方便开发者能够最便捷的获得真实的应用仿真体验，减少开发中的系统联调尝试，我们提供 DevBox 为开发者提供自动快速构建应用沙盒的开发工具集。 + +- DevBox 提供了哪些功能？ + + - 在 DevBox 中，你可以创建一个应用，生成 Olares 应用的 Chart 包。接着你可以修改这个应用 Chart 的部署脚本，移植一个现有的应用，以 Olares 的方式部署到系统中。在修改过程中，你可以尝试安装，检查错误。测试通过后，可下载对应的应用 Chart，提交给 Olares 的 [Market 仓库](https://github.com/beclab/apps)。 + + - 除了移植现有应用，你还可以创建一个全新的应用，在 DevBox 完成整个应用的开发到上线的工作。DevBox 中提供了在线的开发容器，开发者可以在真实的环境中完成代码开发，在程序中调用系统的其他接口或者数据库集群等等。 \ No newline at end of file diff --git a/docs/zh/developer/install/activate-olares.md b/docs/zh/developer/install/activate-olares.md new file mode 100644 index 000000000..6b7359675 --- /dev/null +++ b/docs/zh/developer/install/activate-olares.md @@ -0,0 +1,37 @@ +--- +search: false +--- +## 激活 Olares + +使用向导 URL 和初始一次性密码进行激活和 Olares 初始化配置。 + +1. 在浏览器中输入向导 URL。进入欢迎页面后，按任意键继续。 + + ![打开向导](/images/manual/get-started/open-wizard.png#bordered) +2. 输入一次性密码，点击**继续**。 + + ![输入密码](/images/manual/get-started/wizard-enter-password.png#bordered) +3. 选择系统语言。 + + ![选择语言](/images/manual/get-started/select-language.png#bordered) +4. 使用 LarePass 应用激活 Olares。 + + a. 打开 LarePass 应用，点击**扫描二维码**，扫描向导页面上的二维码完成激活。 + :::warning 检查网络连接 + 为避免激活失败，请确保你的手机和 Olares 设备连接到同一网络。 + ::: + + ![激活 Olares](/images/manual/get-started/activate-olares.png#bordered) + + b. 按照 LarePass 上的提示重置 Olares 的登录密码。 + + ::: tip 使用相同的 ID 重新激活 Olares + + 如果你重新安装了 Olares，原有实例将不可用。要使用同一个 ID 重新激活 Olares： + 1. 在手机上打开 LarePass，你将看到红色提示：“未发现运行中的的 Olares”。 + 2. 点击**了解更多** > **重新激活**，进入二维码扫描页面。 + 3. 点击**扫描二维码**，扫描向导页面上的二维码以完成激活。 + ::: + + +设置成功后，LarePass 应用会自动返回主界面，向导页面则会跳转到登录界面。 \ No newline at end of file diff --git a/docs/zh/developer/install/additional-installations.md b/docs/zh/developer/install/additional-installations.md new file mode 100644 index 000000000..b18bcafe4 --- /dev/null +++ b/docs/zh/developer/install/additional-installations.md @@ -0,0 +1,21 @@ +--- +description: 在 macOS、Windows、PVE、树莓派等平台的容器或虚拟环境中安装 Olares，用于开发和测试场景的安装指南。不适用于生产环境。 +--- + +# 其他安装方式 + +本部分文档介绍如何在 Linux、macOS、Windows、PVE 或 Raspberry Pi 平台上的容器化或虚拟环境下安装和运行 Olares，**仅适用于开发或测试环境**。 + +::: tip 生产环境安装建议 +Olares 已针对 Linux 系统（Ubuntu 或 Debian）进行了优化。我们推荐[通过脚本在 Linux 上安装 Olares](/manual/get-started/install-olares.md)，以在生产环境中获得最佳的性能与稳定性。 +::: + +在安装之前，请先[创建 Olares ID](../../manual/get-started/create-olares-id.md)，并确保操作系统与硬件满足最低要求。 + +请选择你的平台开始安装： +- [在 Linux 上安装（通过 Docker 镜像）](linux-via-docker-compose.md) +- [在 macOS 上安装](mac.md) +- [在 Windows（WSL 2）上安装](windows.md) +- [在 PVE 上安装](pve.md) +- [在 LXC 上安装](lxc.md) +- [在树莓派上安装](raspberry-pi.md) \ No newline at end of file diff --git a/docs/zh/developer/install/cli/backups-backup.md b/docs/zh/developer/install/cli/backups-backup.md new file mode 100644 index 000000000..fe9a834e9 --- /dev/null +++ b/docs/zh/developer/install/cli/backups-backup.md @@ -0,0 +1,83 @@ +--- +outline: [2, 3] +--- +# `backup` +:::warning +必须先运行 `olares-cli backups download` 命令来安装 Restic，否则直接运行此命令将返回错误。 +::: +## 命令说明 +`backup` 子命令用于将数据备份到指定的存储后端。它能确保数据安全存储，以便在需要时进行恢复。 + +```bash +olares-cli backups backup <存储后端> --path <备份路径> --repo-name <仓库名称> [选项] +``` + +## 通用选项 +以下选项适用于所有后端： + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|---------------|------|----------------|----------|--------| +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | +| `--path` | | 指定要备份的目录。 | 否 | 无 | +| `--repo-name` | | 指定备份仓库的名称。 | 否 | 无 | + +## 存储后端配置选项 +### 腾讯云对象存储（`cos`）选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-----------------------|----|------------------------------------------------------------------------------|----------|----------| +| `--access-key` | | 设置腾讯云 COS 的访问密钥。 | 否 | 无 | +| `--endpoint` | | 设置腾讯云 COS 的终端节点，格式如：`https://cos.{region}.myqcloud.com/{bucket}/{prefix}`。 | 否 | 无 | +| `--limit-upload-rate` | | 设置上传速度的最大值，单位为 KiB/s。 | 否 | 不限速 | +| `--secret-access-key` | | 设置腾讯云 COS 的密钥。 | 否 | 无 | + +### 本地文件系统（`fs`）选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|--------------|----|--------------------|----------|--------| +| `--endpoint` | | 指定存储备份的本地目录路径。 | 否 | 无 | + +### Amazon S3 选项（`s3`） + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-----------------------|----|------------------------------------------------------------------------------|----------|----------| +| `--access-key` | | 设置 Amazon S3 的访问密钥。 | 否 | 无 | +| `--endpoint` | | 设置 Amazon S3 的终端节点，格式如：`https://{bucket}.{region}.amazonaws.com/{prefix}`。 | 否 | 无 | +| `--limit-upload-rate` | | 设置上传速度的最大值，单位为 KiB/s。 | 否 | 不限速 | +| `--secret-access-key` | | 设置 Amazon S3 的密钥。 | 否 | 无 | + +### Olares Space 选项（`space`） + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------------------------|----|---------------------------------------------------------------------|----------|----------| +| `--access-token` 1 | | 设置 Olares Space 的访问令牌。 | 否 | 无 | +| `--cloud-api-mirror` | | 设置云 API 镜像地址。 | 否 | 无 | +| `--cloud-name` | | 设置 Olares Space 实例的云名称。
可通过 [`region`](./backups-region.md) 子命令获取。 | 否 | 无 | +| `--cluster-id` 2 | | 设置用于存储备份的集群 ID。 | 否 | 无 | +| `--limit-upload-rate` | | 设置上传速度的最大值，单位为 KiB/s。 | 否 | 不限速 | +| `--olares-did` 1 | | 设置 Olares DID。 | 否 | 无 | +| `--region-id` | | 设置 Olares Space 实例的区域 ID。
可通过 [`region`](./backups-region.md) 子命令获取。 | 否 | 无 | + +1. 要获取访问令牌和 Olares DID，请在登录 Olares Space 后检查页面网络请求的负载。`token` 字段对应访问令牌，`userid` 字段对应 Olares DID。 + +2. 要获取集群 ID，请运行以下命令： + ```bash + kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}' + ``` +## 使用示例 +```bash +# 备份到腾讯云对象存储 +olares-cli backups backup cos --path /data --repo-name my_repo \ + --access-key YOUR_KEY \ + --secret-access-key YOUR_SECRET \ + --endpoint https://cos.region.myqcloud.com/bucket/prefix + +# 备份到 Olares Space +olares-cli backups backup space --path /data --repo-name my_repo \ + --access-token YOUR_ACCESS_TOKEN \ + --cloud-api-mirror https://api-mirror.example.com \ + --cloud-name my_cloud \ + --region-id region_1 \ + --cluster-id cluster_12345 \ + --olares-did did:xyz123 +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/backups-download.md b/docs/zh/developer/install/cli/backups-download.md new file mode 100644 index 000000000..c87134eb3 --- /dev/null +++ b/docs/zh/developer/install/cli/backups-download.md @@ -0,0 +1,20 @@ +# `download` + +## 命令说明 +`download` 子命令用于下载 Restic 工具。Restic 是执行备份和恢复操作的必需工具，该命令可确保系统上已安装此工具。 + +```bash +olares-cli backups download [选项] +``` +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|----------------------|------|-----------------------------|----------|------------| +| `--download-cdn-url` | | 下载 Restic 工具的 CDN 地址。 | 否 | 系统默认 URL | +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | + +## 使用示例 +```bash +# 通过自定义 CDN 地址下载 Restic +olares-cli backups download --download-cdn-url https://custom-cdn.example.com/restic +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/backups-region.md b/docs/zh/developer/install/cli/backups-region.md new file mode 100644 index 000000000..16f8873c5 --- /dev/null +++ b/docs/zh/developer/install/cli/backups-region.md @@ -0,0 +1,27 @@ +# `region` + +## 命令说明 +`region` 子命令用于获取云名称和区域 ID。该命令专门用于存储后端为 Olares Space 的场景。 +```bash +olares-cli backups region space [选项] +``` + +## 选项 + +| 名称 | 简写 | 用途 | +|-------------------------------|------|------------------------| +| `--access-token` 1 | | 设置 Olares Space 的访问令牌。 | +| `--cloud-api-mirror` | | 设置云 API 镜像地址。 | +| `--help` | `-h` | 显示命令帮助信息。 | +| `--olares-did` 1 | | 设置 Olares DID。 | + +1. 要获取访问令牌和 Olares DID，请在登录 Olares Space 后检查页面网络请求的负载。`token` 字段对应访问令牌，`userid` 字段对应 Olares DID。 + +## 使用示例 +```bash +# 查询云名称和区域 ID +olares-cli backups region space \ +--access-token YOUR_ACCESS_TOKEN \ +--cloud-api-mirror https://api-mirror.example.com \ +--olares-did did:xyz123 +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/backups-restore.md b/docs/zh/developer/install/cli/backups-restore.md new file mode 100644 index 000000000..364e94455 --- /dev/null +++ b/docs/zh/developer/install/cli/backups-restore.md @@ -0,0 +1,82 @@ +--- +outline: [2, 3] +--- +# `restore` +:::warning +必须先运行 `olares-cli backups download` 命令来安装 Restic，否则直接运行此命令将返回错误。 +::: +## 命令说明 +`restore` 子命令用于从指定的备份仓库和快照中恢复数据到目标目录。 + +```bash +olares-cli backups restore <存储后端> --path <恢复路径> --repo-name <仓库名称> --snapshot-id <快照ID> [选项] +``` + +## 通用选项 +以下选项适用于所有后端： + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-----------------|------|------------------------|----------|--------| +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | +| `--path` | | 设置数据恢复的目标目录路径。 | 否 | 无 | +| `--repo-name` | | 设置要恢复数据的备份仓库名称。 | 否 | 无 | +| `--snapshot-id` | | 设置要恢复的快照 ID。 | 否 | 无 | + +## 存储后端配置选项 + +### 腾讯云对象存储（`cos`）选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------------------|----|------------------------------------------------------------------------------|----------|----------| +| `--access-key` | | 设置腾讯云 COS 的访问密钥。 | 否 | 无 | +| `--endpoint` | | 设置腾讯云 COS 的终端节点，格式如：`https://cos.{region}.myqcloud.com/{bucket}/{prefix}`。 | 否 | 无 | +| `--limit-download-rate` | | 设置下载速度的最大值，单位为 KiB/s。 | 否 | 不限速 | +| `--secret-access-key` | | 设置腾讯云 COS 的密钥。 | 否 | 无 | + +### 本地文件系统（`fs`）选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|---------------|----|----------------------|----------|--------| +| `--endpoint` | | 设置存储备份的本地目录路径。 | 否 | 无 | +| `--olares-id` | | 设置 Olares ID。 | 否 | 无 | + +### Amazon S3 选项（`s3`） + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------------------|----|------------------------------------------------------------------------------|----------|----------| +| `--access-key` | | 设置 Amazon S3 的访问密钥。 | 否 | 无 | +| `--endpoint` | | 设置 Amazon S3 的终端节点，格式如：`https://{bucket}.{region}.amazonaws.com/{prefix}`。 | 否 | 无 | +| `--limit-download-rate` | | 设置下载速度的最大值，单位为 KiB/s。 | 否 | 不限速 | +| `--secret-access-key` | | 设置 Amazon S3 的密钥。 | 否 | 无 | + +### Olares Space 选项（`space`） + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------------------------|----|---------------------------------------------------------------------|----------|----------| +| `--access-token` 1 | | 设置 Olares Space 的访问令牌。 | 否 | 无 | +| `--cloud-api-mirror` | | 设置云 API 镜像地址。 | 否 | 无 | +| `--cloud-name` | | 设置 Olares Space 实例的云名称。
可通过 [`region`](./backups-region.md) 子命令获取。 | 否 | 无 | +| `--cluster-id` 2 | | 设置用于存储备份的集群 ID。 | 否 | 无 | +| `--limit-download-rate` | | 设置下载速度的最大值，单位为 KiB/s。 | 否 | 不限速 | +| `--olares-did` 1 | | 设置 Olares DID。 | 否 | 无 | +| `--region-id` | | 设置 Olares Space 实例的区域 ID。
可通过 [`region`](./backups-region.md) 子命令获取。 | 否 | 无 | + +1. 要获取访问令牌和 Olares DID，请在登录 Olares Space 后检查页面网络请求的负载。`token` 字段对应访问令牌，`userid` 字段对应 Olares DID。 + +2. 要获取集群 ID，请运行以下命令： + ```bash + kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}' + ``` +## 使用示例 +```bash +# 从腾讯云对象存储恢复数据 +olares-cli backups restore cos --path /data_restore --repo-name my_repo \ + --snapshot-id snapshot_12345 \ + --access-key YOUR_KEY \ + --secret-access-key YOUR_SECRET \ + --endpoint https://cos.region.myqcloud.com/bucket/prefix + +# 从本地文件系统恢复数据 +olares-cli backups restore fs --path /data_restore --repo-name my_repo \ + --snapshot-id snapshot_12345 --endpoint /backup_repo +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/backups-snapshots.md b/docs/zh/developer/install/cli/backups-snapshots.md new file mode 100644 index 000000000..d2d912159 --- /dev/null +++ b/docs/zh/developer/install/cli/backups-snapshots.md @@ -0,0 +1,72 @@ +--- +outline: [2, 3] +--- +# `snapshots` +:::warning +必须先运行 `olares-cli backups download` 命令来安装 Restic，否则直接运行此命令将返回错误。 +::: +## 命令说明 +`snapshots` 子命令用于列出指定备份仓库中的所有可用快照。它支持多种存储后端，并提供必要的选项来进行身份验证和查询快照。 +```bash +olares-cli backups snapshots <存储后端> --repo-name <仓库名称> [选项] +``` +## 通用选项 +以下选项适用于所有后端： + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|---------------|------|----------------------|----------|--------| +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | +| `--repo-name` | | 设置要查询的备份仓库名称。 | 否 | 无 | + +## 存储后端配置选项 + +### 腾讯云对象存储（`cos`）选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|---------------------|----|------------------------------------------------------------------------------|----------|--------| +| `--access-key` | | 设置腾讯云 COS 的访问密钥。 | 否 | 无 | +| `--endpoint` | | 设置腾讯云 COS 的终端节点，格式如：`https://cos.{region}.myqcloud.com/{bucket}/{prefix}`。 | 否 | 无 | +| `--secret-access-key` | | 设置腾讯云 COS 的密钥。 | 否 | 无 | | + +### 本地文件系统（`fs`）选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|--------------|----|----------------------|----------|--------| +| `--endpoint` | | 设置存储备份的本地目录路径。 | 否 | 无 | + +### Amazon S3 选项（`s3`） + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|---------------------|----|------------------------------------------------------------------------------|----------|--------| +| `--access-key` | | 设置 Amazon S3 的访问密钥。 | 否 | 无 | +| `--endpoint` | | 设置 Amazon S3 的终端节点，格式如：`https://{bucket}.{region}.amazonaws.com/{prefix}`。 | 否 | 无 | +| `--secret-access-key` | | 设置 Amazon S3 的密钥。 | 否 | 无 | + +### Olares Space 选项（`space`） + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------------------------|----|---------------------------------------------------------------------|----------|--------| +| `--access-token` 1 | | 设置 Olares Space 的访问令牌。 | 否 | 无 | +| `--cloud-api-mirror` | | 设置云 API 镜像地址。 | 否 | 无 | +| `--cloud-name` | | 设置 Olares Space 实例的云名称。
可通过 [`region`](./backups-region.md) 子命令获取。 | 否 | 无 | +| `--cluster-id` 2 | | 设置用于存储备份的集群 ID。 | 否 | 无 | +| `--olares-did` 1 | | 设置 Olares DID。 | 否 | 无 | +| `--region-id` | | 设置 Olares Space 实例的区域 ID。
可通过 [`region`](./backups-region.md) 子命令获取。 | 否 | 无 | + +1. 要获取访问令牌和 Olares DID，请在登录 Olares Space 后检查页面网络请求的负载。`token` 字段对应访问令牌，`userid` 字段对应 Olares DID。 + +2. 要获取集群 ID，请运行以下命令： + ```bash + kubectl get terminus -o jsonpath='{.items[*].metadata.labels.bytetrade\.io/cluster-id}' + ``` +## 使用示例 +```bash +# 列出腾讯云对象存储中的快照 +olares-cli backups snapshots cos --repo-name my_repo \ + --access-key YOUR_KEY \ + --secret-access-key YOUR_SECRET \ + --endpoint https://cos.region.myqcloud.com/bucket/prefix + +# 列出本地文件系统中的快照 +olares-cli backups snapshots fs --repo-name my_repo --endpoint /backup_repo +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/backups.md b/docs/zh/developer/install/cli/backups.md new file mode 100644 index 000000000..6d2e132e8 --- /dev/null +++ b/docs/zh/developer/install/cli/backups.md @@ -0,0 +1,23 @@ +# `backups` +`backups` 命令提供了一组数据备份、恢复和快照管理工具。它支持多种存储后端，包括腾讯云对象存储、Amazon S3、本地文件系统和 Olares Space。 + +## 子命令 + +| 子命令 | 描述 | +|-------------|----------------------------------------| +| `download` | 下载 Restic 依赖工具。 | +| `region` | 获取云名称和区域 ID。仅当 Olares Space 作为存储后端时使用。 | +| `backup` | 将数据备份到指定的存储后端。 | +| `restore` | 从指定的存储后端恢复数据。 | +| `snapshots` | 管理和查看备份快照。 | + +## 支持的存储后端 + +使用 `backup` 和 `restore` 命令时，需要通过 `<存储后端>` 参数指定存储类型。Olares CLI 支持以下存储后端： + +| 存储后端 | 描述 | +|---------|-------------------------------------| +| `cos` | 腾讯云对象存储（COS）。需要提供访问密钥、密钥和终端节点。 | +| `s3` | Amazon 对象存储服务（S3）。需要提供访问密钥、密钥和终端节点。 | +| `fs` | 本地文件系统。无需提供凭据。 | +| `space` | Olares Space。需要提供访问令牌。 | \ No newline at end of file diff --git a/docs/zh/developer/install/cli/change-ip.md b/docs/zh/developer/install/cli/change-ip.md new file mode 100644 index 000000000..028e4f248 --- /dev/null +++ b/docs/zh/developer/install/cli/change-ip.md @@ -0,0 +1,33 @@ +# `change-ip` +:::warning IP 地址需要手动更新的情况 +当 Olares 部署在虚拟化环境中时（如 macOS 上的 Minikube 或 Windows 上的 WSL），如果宿主系统的 IP 地址发生变化（比如切换 Wi-Fi 网络），可能会导致 Olares 无法访问。这是因为 NAT 网关和 DNS 配置与新的 IP 地址不匹配。此时需要手动更新 IP 地址，以确保 Olares 能够正确路由流量。 +::: + +## 命令说明 +更新所有 Olares 组件使用的本地 IP 地址。 + +```bash +olares-cli change-ip [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|------------------|------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------| +| `--base-dir` | `-b` | 设置 Olares 的基础目录。 | 否 | `$HOME/.olares` | +| `--distribution` | `-d` | 指定 WSL 发行版名称，仅适用于 Windows。 | 否 | `Ubuntu` | +| `--help` | `-h` | 显示帮助信息。 | 否 | 无 | +| `--profile` | `-p` | 设置 Minikube 配置文件名称，仅适用于 macOS。 | 否 | `olares-0` | +| `--version` | `-v` | 指定 Olares 版本。
版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/beclab/Olares/releases)。 | 否 | 当前安装版本 | + +## 使用示例 +- macOS: +```bash +# 指定 Minikube 配置文件名称并更新 IP +olares-cli change-ip --profile olares-0 +``` +- Windows WSL: +```bash +# 指定 WSL 发行版并更新 IP +olares-cli change-ip --distribution Ubuntu +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/download.md b/docs/zh/developer/install/cli/download.md new file mode 100644 index 000000000..0e1f5c26d --- /dev/null +++ b/docs/zh/developer/install/cli/download.md @@ -0,0 +1,45 @@ +# `download` + +## 命令说明 + +`download` 命令用于下载在本地机器上安装 Olares 所需的软件包和组件。它支持下载组件、检查安装包状态以及获取配置清单文件。 +```bash +olares-cli download <子命令> [选项] +``` + +## 子命令 + +| 名称 | 简写 | 用途 | 示例 | +|-------------|-----|------------------|----------------------------------------| +| `check` | | 检查 Olares 安装包的状态 | `olares-cli download check` | +| `component` | `c` | 下载 Olares 组件 | `olares-cli download component` | +| `wizard` | `w` | 下载配置清单文件 | `olares-cli download wizard` | + +## 选项 +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|----------------------|------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------|--------------| +| `--base-dir` | `-b` | 设置 Olares 的基础目录。 | 否 | `$HOME/.olares`| +| `--download-cdn-url` | | 设置 CDN 加速下载地址，格式为 `https://example.cdn.com`。 | 否 | 默认地址 | +| `--help` | `-h` | 显示帮助信息。 | 否 | 无 | +| `--kube` | | 指定 Kubernetes 类型。
支持 `k3s` 和 `k8s`。 | 否 | `k3s` | +| `--version` | `-v` | 指定 Olares 版本。
版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/beclab/Olares/releases)。 | 否 | 当前安装版本 | + +## 使用示例 +```bash +# 指定存储所有下载组件的基础目录 +olares-cli download component -b /custom/path + +# 指定用于下载 Olares 组件的 CDN 加速地址 +olares-cli download component --download-cdn-url https://my.cdn.com + +# 指定安装的 Kubernetes 类型 +olares-cli download component --kube k8s + +# 设置配置清单文件的路径 +olares-cli download component --manifest /custom/path/manifest.json + +# 指定要下载的 Olares 软件包和组件版本 +olares-cli download component -v 1.11.0 +``` + + diff --git a/docs/zh/developer/install/cli/gpu.md b/docs/zh/developer/install/cli/gpu.md new file mode 100644 index 000000000..554d233d9 --- /dev/null +++ b/docs/zh/developer/install/cli/gpu.md @@ -0,0 +1,53 @@ +# `gpu` + +## 命令说明 + +`gpu` 命令用于管理 GPU 功能，包括安装、启用、禁用和卸载 GPU 驱动及相关组件，以及查看 GPU 安装状态。 + +```bash +olares-cli gpu <子命令> [选项] +``` + +:::info +- 通常情况下，Olares 安装脚本会自动检测显卡硬件和 CUDA 驱动，并根据检测结果自动安装、启用显卡相关组件和服务。 +- 当前仅支持 NVIDIA 显卡。 +::: + +## 子命令 + +| 子命令 | 描述 | +|-------------|------------------------------------------------------------------| +| `install` | 安装 GPU 驱动和相关依赖。| +| `enable` | 启用 GPU 功能，支持 GPU 应用运行。 | +| `disable` | 禁用 GPU 功能，停止支持 GPU 应用运行。 | +| `uninstall` | 卸载 GPU 驱动和相关程序。 | +| `status` | 查看 GPU 驱动和 CUDA 版本信息，以及 GPU 相关服务的运行状态。 | + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|--------------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------| +| `--base-dir` | `-b` | 指定安装的基础目录。 | 否 | `$HOME/.olares` | +| `--version` | `-v` | 安装指定 Olares 版本的 GPU 驱动及组件。版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/beclab/Olares/releases)。 | 否 | 当前已安装版本 | +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | + +## 使用示例 +```bash +# 安装指定 Olares 版本的 GPU 驱动及依赖至指定目录 +olares-cli gpu install --base-dir /home/olares/.olares --version 1.11.1-rc.4 + +# 启用 GPU 功能 +olares-cli gpu enable + +# 查看 GPU 驱动和服务状态 +olares-cli gpu status + +# 禁用 GPU 功能 +olares-cli gpu disable + +# 卸载 GPU 驱动及组件 +olares-cli gpu uninstall + +``` + + diff --git a/docs/zh/developer/install/cli/info.md b/docs/zh/developer/install/cli/info.md new file mode 100644 index 000000000..fde0e7eff --- /dev/null +++ b/docs/zh/developer/install/cli/info.md @@ -0,0 +1,14 @@ +# `info` + +## 命令说明 +`info` 命令用于显示当前安装的 Olares 版本信息。 + +```bash +olares-cli info +``` + +## 参数标记 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|----------|------|------------------|----------|--------| +| `--help` | `-h` | 显示命令的帮助信息。 | 否 | 无 | \ No newline at end of file diff --git a/docs/zh/developer/install/cli/install.md b/docs/zh/developer/install/cli/install.md new file mode 100644 index 000000000..d8b836c3f --- /dev/null +++ b/docs/zh/developer/install/cli/install.md @@ -0,0 +1,18 @@ +# `install` + +## 命令说明 +`install` 命令用于在系统上安装 Olares。通过各种选项可以自定义安装过程，比如指定安装目录、Kubernetes 类型或 Minikube 配置文件等。 + +```bash +olares-cli install [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------|------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------------| +| `--base-dir`| `-b` | 设置 Olares 的基础目录。 | 否 | `$HOME/.olares` | +| `--help` | `-h` | 显示帮助信息。 | 否 | 无 | +| `--kube` | | 指定 Kubernetes 类型。
支持 `k3s` 和 `k8s`。 | 否 | `k3s` | +| `--profile` | `-p` | 设置 Minikube 配置文件名称，仅适用于 macOS。 | 否 | `olares-0` | +| `--version` | `-v` | 指定 Olares 版本。
版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/beclab/Olares/releases)。 | 否 | `prepare` 阶段安装的版本 | diff --git a/docs/zh/developer/install/cli/logs.md b/docs/zh/developer/install/cli/logs.md new file mode 100644 index 000000000..3ebad5e39 --- /dev/null +++ b/docs/zh/developer/install/cli/logs.md @@ -0,0 +1,41 @@ +# `logs` + +## 命令说明 +`logs` 命令用于获取本机上的 Olares 组件和服务日志。它会检查以下每个组件，如果找到则收集其日志，未找到则跳过： + +* K3s/Kubelet 日志 +* Containerd 日志 +* JuiceFS 日志 +* Redis 日志 +* MinIO 日志 +* etcd 日志 +* olaresd 日志 +* Kubernetes Pod 信息和日志 +* Kubernetes 节点信息 + +```bash +olares-cli logs [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|------------------------|------|----------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------------| +| `--components` | | 指定要收集日志的组件（用逗号分隔）。
支持的组件：`k3s`、`containerd`、`olaresd`、`kubelet`、`juicefs`、`redis`、`minio`、`etcd`、`NetworkManager`。 | 否 | 所有可检测到的组件日志 | +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | +| `--ignore-kube-errors` | | 忽略 `kubectl` 命令的错误（例如无法连接 Kubernetes API）并继续收集其他日志。 | 否 | `false` | +| `--max-lines` | | 限制每个组件日志的最大行数，避免日志文件过大。 | 否 | `3000` 行 | +| `--output-dir` | | 设置日志保存目录。如果目录不存在则自动创建。 | 否 | `./olares-logs` | +| `--since` | | 设置日志收集的时间范围（例如 `5s`、`2m`、`3h`）。 | 否 | 最近 `7d`（7天）的日志 | + +## 使用示例 +```bash +# 使用默认设置收集所有日志 +olares-cli logs + +# 收集指定组件的日志 +olares-cli logs --components k3s,redis,minio + +# 只收集最近 3 小时的日志 +olares-cli logs --since 3h +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/node.md b/docs/zh/developer/install/cli/node.md new file mode 100644 index 000000000..e0f2009be --- /dev/null +++ b/docs/zh/developer/install/cli/node.md @@ -0,0 +1,53 @@ +# `node` + +## 命令说明 + +`node` 命令用于管理节点相关的操作。 + +```bash +olares-cli node <子命令> [选项] +``` + +## 子命令 + +| 子命令 | 描述 | +|--------------|----------------------------------------------------| +| `masterinfo` | 获取主节点的系统信息，并检查当前节点是否满足作为从节点加入集群的条件。 | +| `add` | 将当前节点添加到已有的 Olares 集群中。该节点的环境必须已满足 Olares 的所有前置条件。 | + +## 选项 + + + +| 选项 | 简写| 用途 | 是否必需 | 默认值 | +|---------------------------------|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------| +| `--base-dir` | `-b` | 指定安装的基础目录。 | 否 | `$HOME/.olares` | +| `--master-host` | | 指定主节点的 IP 地址。 | 是 | 无 | +| `--master-node-name` | | 指定主节点的 Kubernetes 节点名称。 | 否 | 无 | +| `--master-ssh-user` | | 设置主节点 SSH 登录的 Linux 用户名。 | 否 | `root` | +| `--master-ssh-password` | | 设置 Linux 用户的密码。 | 当指定非 root 登录用户时必填。 | 无 | +| `--master-ssh-private-key-path` | | 指定 Linux 用户 SSH 认证的私钥路径。 | 否 | `/root/.ssh/id_rsa` | +| `--master-ssh-port` | | 设置主节点 SSH 服务的监听端口。 | 否 | `22` | +| `--version` | `-v` | 指定 Olares 版本。版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/beclab/Olares/releases)。 | 否 | 当前已安装版本 | +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | + +## 使用示例 + +```bash +# 获取 IP 为 192.168.1.15 的主节点系统信息 +olares-cli node masterinfo --master-host 192.168.1.15 + +# 如需使用指定的 SSH 密钥进行认证 +olares-cli node masterinfo --master-host 192.168.1.15 --master-ssh-private-key-path /home/olares/.ssh/id_rsa + +# 使用非 root 用户时，需指定用户名和密码 +olares-cli node masterinfo --master-host 192.168.1.15 --master-ssh-user olares --master-ssh-password password123 + +# 将当前节点添加到主节点 IP 为 192.168.1.15 的集群中 +olares-cli node add --master-host 192.168.1.15 + +# 指定自定义的安装基础目录 +olares-cli node add --base-dir /custom/path --master-host 192.168.1.15 +``` + + diff --git a/docs/zh/developer/install/cli/olares-cli.md b/docs/zh/developer/install/cli/olares-cli.md new file mode 100644 index 000000000..b460a6306 --- /dev/null +++ b/docs/zh/developer/install/cli/olares-cli.md @@ -0,0 +1,63 @@ +--- +outline: [2, 3] +--- +# Olares 命令行工具 + +:::warning 版本兼容信息 +此 Olares CLI 版本适用于 Olares 1.12.X。 +::: + +Olares 命令行工具（Olares CLI）面向开发者和系统管理员，用于管理和排查 Olares 系统，提供从安装配置到资源管理和诊断等多种功能。 + +使用 Olares 命令行工具，你可以简化系统兼容性验证、资源下载、节点管理、日志收集等任务。本文档将介绍命令行工具的语法，并详细说明各类操作的可用命令。 + +:::info 需要 root 权限 +大多数 `olares-cli` 命令都需要 root 权限。请使用 root 用户执行命令，或在命令前加上 `sudo`。 +::: + +:::info 在 WSL 中使用 Olares CLI +如果通过 WSL（Windows Subsystem for Linux）方式安装了 Olares，需要在 WSL 环境中使用 `olares-cli`。 + +在 PowerShell 中执行以下命令进入 WSL： + +```powershell +wsl -d Ubuntu +``` +::: + +## 语法 +Olares 命令行工具使用如下语法： + +> `olares-cli 命令 [子命令] [选项]` + +其中： +- `命令`：指定要执行的主要操作，例如 `olares-cli install`。 +- `子命令`：进一步指定命令的具体任务，适用于支持子操作的命令。例如 `wizard` 或 `component`。 +- `选项`：可选参数，用于修改命令的行为。包括标志（flags）和带参数的选项。 + +通过 Olares 命令行工具，你可以临时覆盖某些 Olares 默认设置。每个选项仅对当前执行的命令生效。 + +例如，在执行 `olares-cli download wizard` 时使用 `--base-dir` 选项，只会影响向导的下载过程，而不会改变其他命令（如“安装”阶段）的基础目录。 + +如需查看任何命令的详细帮助信息，请运行 `olares-cli help`。 + +## 可用命令列表 + +| 操作 | 语法 | 说明 | +|--------------------|-----------------------------------------|--------------------------------| +| `gpu` | `olares-cli gpu <子命令> [选项]` | 管理 GPU 相关的操作。 | +| `info` | `olares-cli info <子命令> [选项]` | 显示当前设备的操作系统信息。 | +| `node` | `olares-cli node <子命令> [选项]` | 管理节点相关的操作。 | +| `backups` | `olares-cli backups <子命令> [选项]` | 管理备份相关操作。 | +| `change-ip` | `olares-cli change-ip [选项]` | 修改 Olares OS 的 IP 地址。 | +| `download` | `olares-cli download <子命令> [选项]` | 下载指定资源。 | +| `info` | `olares-cli info [选项]` | 显示已下载的 Olares OS 的常规信息。 | +| `install` | `olares-cli install [选项]` | 部署 Olares 的系统级和用户级组件。 | +| `logs` | `olares-cli logs [选项]` | 收集 Olares 系统组件的日志，用于调试和故障排查。 | +| `precheck` | `olares-cli precheck [选项]` | 检查系统环境是否满足 Olares 安装要求。 | +| `prepare` | `olares-cli prepare [选项]` | 为安装过程准备环境，包括设置 Olares 的基础服务和配置 | +| `release` | `olares-cli release [选项]` | 打包 Olares 安装资源以供分发或部署。 | +| `start` | `olares-cli start [选项]` | 启动 Olares 服务和组件。 | +| `stop` | `olares-cli stop [选项]` | 停止 Olares 服务和组件。 | +| `uninstall` | `olares-cli uninstall [选项]` | 完全卸载 Olares，或将安装回滚到特定阶段。 | + diff --git a/docs/zh/developer/install/cli/osinfo.md b/docs/zh/developer/install/cli/osinfo.md new file mode 100644 index 000000000..87c4a65b7 --- /dev/null +++ b/docs/zh/developer/install/cli/osinfo.md @@ -0,0 +1,21 @@ +# `osinfo` + +## 命令说明 + +`osinfo` 命令用于获取当前设备操作系统的详细信息。它能够检索并显示元数据信息，包括 `OS_TYPE`、`OS_PLATFORM`、`OS_ARCH`、`OS_VERSION`、`OS_KERNEL` 和 `OS_INFO` 等。 + +```bash +olares-cli osinfo <子命令> [选项] +``` + +## 子命令 + +| 名称 | 用途 | +|--------|---------------| +| `show` | 显示当前设备的操作系统信息 | + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|----------|------|------------------|----------|--------| +| `--help` | `-h` | 显示命令的帮助信息。 | 否 | 无 | \ No newline at end of file diff --git a/docs/zh/developer/install/cli/precheck.md b/docs/zh/developer/install/cli/precheck.md new file mode 100644 index 000000000..e27c7ee3e --- /dev/null +++ b/docs/zh/developer/install/cli/precheck.md @@ -0,0 +1,16 @@ +# `precheck` + +## 命令说明 +`precheck` 命令用于检查系统环境是否满足安装 Olares 的所有前置条件。 + +```bash +olares-cli precheck [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------|------|------------------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------| +| `--base-dir`| `-b` | 设置 Olares 的基础目录。 | 否 | `$HOME/.olares` | +| `--help` | `-h` | 显示帮助信息。 | 否 | 无 | +| `--version` | `-v` | 指定 Olares 版本。
版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/beclab/Olares/releases)。 | 否 | 当前安装版本 | \ No newline at end of file diff --git a/docs/zh/developer/install/cli/prepare.md b/docs/zh/developer/install/cli/prepare.md new file mode 100644 index 000000000..0825704e8 --- /dev/null +++ b/docs/zh/developer/install/cli/prepare.md @@ -0,0 +1,26 @@ +# `prepare` + +## 命令说明 +`prepare` 命令用于配置 Olares 运行所需的环境，包括安装依赖项、导入容器镜像和启动 Olares 守护进程（`olaresd`）。 + +```bash +olares-cli prepare [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|----------------------|------|------------------------------------------------------------------------------------------------------------------------------------------|----------|------------------| +| `--base-dir` | `-b` | 设置 Olares 的基础目录。 | 否 | `$HOME/.olares` | +| `--help` | `-h` | 显示帮助信息。 | 否 | 无 | +| `--kube` | `-k` | 指定 Kubernetes 类型。支持 `k3s` 和 `k8s`。 | 否 | `k3s` | +| `--profile` | `-p` | 设置 Minikube 配置文件名称，仅适用于 macOS。 | 否 | `olares-0` | +| `--registry-mirrors` | `-r` | 设置 Docker 容器镜像仓库的镜像源。多个镜像源之间使用英文逗号分隔。 | 否 | 无 | +| `--with-juicefs` | `-j` | 将 JuiceFS 配置为 Olares 工作负载的根文件系统（rootfs），替代本地磁盘。 | 否 | 无 | +| `--version` | `-v` | 指定 Olares 版本。版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/olares/releases)。 | 否 | 当前安装版本 | + +## 使用示例 +```bash +# 使用 JuiceFS 作为根文件系统 +olares-cli prepare --with-juicefs=true +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/release.md b/docs/zh/developer/install/cli/release.md new file mode 100644 index 000000000..e5ff62fa1 --- /dev/null +++ b/docs/zh/developer/install/cli/release.md @@ -0,0 +1,19 @@ +# `release` + +## 命令说明 +基于本地 Olares 代码仓库构建发布版本。此命令需要在 Olares 代码仓库的根目录下运行。 + +```bash +olares-cli release [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-----------------------------|------|----------------------------------------------------------------------------------------------------------------------------------------------|----------|----------------------------------------| +| `--base-dir` | `-b` | 设置 Olares 的基础目录。 | 否 | `$HOME/.olares` | +| `--download-cdn-url` | | 设置用于下载依赖项和镜像校验和的 CDN URL。 | 否 | `https://dc3p1870nn3cj.cloudfront.net` | +| `--extract` | `-e` | 构建完成后是否将发布包解压到 `--base-dir` 目录下。
如果只需要发布包文件本身，可设为 `false`。 | 否 | `true` | +| `--help` | `-h` | 显示帮助信息。 | 否 | 无 | +| `--ignore-missing-images` | | 从 CDN 下载校验和时是否忽略缺失的镜像。
仅当确定没有新增镜像时才建议禁用此选项，因为新镜像可能尚未上传到 CDN 导致构建失败。 | 否 | `true` | +| `--version` | `-v` | 指定 Olares 版本。
版本号格式为 `x.y.z`（如 `1.10.0`）或包含构建日期（如 `1.10.0-20241109`）。
可用版本请参考 [GitHub Releases](https://github.com/beclab/Olares/releases)。 | 否 | 当前安装版本 | \ No newline at end of file diff --git a/docs/zh/developer/install/cli/start.md b/docs/zh/developer/install/cli/start.md new file mode 100644 index 000000000..6823d2c3f --- /dev/null +++ b/docs/zh/developer/install/cli/start.md @@ -0,0 +1,13 @@ +# `start` + +## 命令说明 +`start` 命令用于启动已停止的 Olares 系统，包括其所有组件和服务。 +```bash +olares-cli start [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|----------|------|----------------|----------|--------| +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | \ No newline at end of file diff --git a/docs/zh/developer/install/cli/stop.md b/docs/zh/developer/install/cli/stop.md new file mode 100644 index 000000000..7c127b940 --- /dev/null +++ b/docs/zh/developer/install/cli/stop.md @@ -0,0 +1,28 @@ +# `stop` + +## 命令说明 +`stop` 命令用于停止已安装（或部分安装）的 Olares 系统中的各个组件。 + +```bash +olares-cli stop [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|--------------------|------|------------------------------------------------------------------------------|----------|----------| +| `--check-interval` | | 设置关闭过程中检查剩余进程的时间间隔（如 `5s`、`2m`、`3h`）。 | 否 | `10s` | +| `--help` | `-h` | 显示命令帮助信息。 | 否 | 无 | +| `--timeout` | | 设置等待优雅关闭的最长时间，超时后将使用 SIGKILL 强制终止（如 `5s`、`2m`、`3h`）。 | 否 | `1m` | + +## 使用示例 +```bash +# 停止 Olares 系统 +olares-cli stop + +# 调整关闭超时时间 +olares-cli stop --timeout 2m + +# 自定义检查间隔时间 +olares-cli stop --check-interval 5s +``` \ No newline at end of file diff --git a/docs/zh/developer/install/cli/uninstall.md b/docs/zh/developer/install/cli/uninstall.md new file mode 100644 index 000000000..ecd299060 --- /dev/null +++ b/docs/zh/developer/install/cli/uninstall.md @@ -0,0 +1,19 @@ +# `uninstall` + +## 命令说明 +卸载 Olares。 + +```bash +olares-cli uninstall [选项] +``` + +## 选项 + +| 选项 | 简写 | 用途 | 是否必需 | 默认值 | +|-------------|------|---------------------------------------------------------------------------------------------------------------------------------------|----------|----------------| +| `--all` | | 完全卸载 Olares，包括在“准备”阶段安装的所有依赖项。 | 否 | 无 | +| `--base-dir`| `-b` | 设置 Olares 的基础目录。 | 否 | `$HOME/.olares` | +| `--help` | `-h` | 显示帮助信息。 | 否 | 无 | +| `--phase` | | 从指定阶段卸载 Olares 并回退到前一个阶段。
例如，使用 `--phase install` 将移除“安装”阶段执行的任务，使系统回退到“准备”阶段。 | 否 | `install` | +| `--quiet` | | 启用静默模式（不显示输出信息）。 | 否 | `false` | +| `--version` | `-v` | 指定要卸载的 Olares 版本。
建议先使用 `olares-cli info` 命令查看已下载的版本。 | 否 | 当前安装版本 | \ No newline at end of file diff --git a/docs/zh/developer/install/environment-variables.md b/docs/zh/developer/install/environment-variables.md new file mode 100644 index 000000000..6b41672f0 --- /dev/null +++ b/docs/zh/developer/install/environment-variables.md @@ -0,0 +1,223 @@ +--- +outline: [2, 3] +description: Olares 提供的环境变量，用于自定义网络、认证、GPU 支持等功能。包含配置示例和详细规格说明。 +--- +# Olares 环境变量参考 + +Olares 提供了丰富的环境变量以满足定制化安装需求。通过修改这些变量，你可以覆盖默认安装设置，实现灵活的个性化安装配置。 + +## 使用示例 + +你可以在运行安装命令前设置环境变量，以自定义安装流程。例如： + +```bash +# 指定安装完整的 Kubernetes (k8s) 而非轻量级 k3s +export KUBE_TYPE=k8s \ +&& curl -sSfL https://olares.sh | bash - +``` + +如果你已预先下载了安装脚本 `install.sh`，也可以使用以下方式： + +```bash +# 指定使用完整的 Kubernetes (k8s) 而非轻量级 k3s +export KUBE_TYPE=k8s && bash install.sh +``` +两种方式的执行效果相同：环境变量 `KUBE_TYPE` 会传递给安装脚本，脚本会根据这个变量来调整其安装逻辑。 + +当然，你也可以组合多个环境变量来实现更灵活的自定义效果。例如中国大陆的用户通过`cn.olares.sh`获取的安装脚本，就是一个在默认安装脚本之上设置了一系列环境变量的脚本： + +```bash +curl -fsSL https://cn.olares.sh +#!/bin/bash + +export FRP_ENABLE=1 \ + FRP_SERVER="http://frp-bj.api.jointerminus.cn" \ + FRP_PORT=0 \ + JUICEFS=0 \ + FRP_AUTH_METHOD="jws" \ + REGISTRY_MIRRORS="https://mirrors.joinolares.cn" \ + DOWNLOAD_CDN_URL="https://cdn.joinolares.cn" \ + MARKET_PROVIDER="appstore-china-server-prod.api.jointerminus.cn" \ + TERMINUS_CERT_SERVICE_API="https://terminus-cert.api.jointerminus.cn" \ + TERMINUS_DNS_SERVICE_API="https://terminus-dnsop.api.jointerminus.cn" \ + DID_GATE_URL="https://did-gate-v3.api.jointerminus.cn/" \ + OLARES_SPACE_URL="https://cloud-api.api.jointerminus.cn/" \ + FIREBASE_PUSH_URL="https://firebase-push-test.api.jointerminus.cn/v1/api/push" \ + FRP_LIST_URL="https://terminus-frp.api.jointerminus.cn/" \ + TAILSCALE_CONTROLPLANE_URL="https://controlplane.api.jointerminus.cn" + +curl -sSfL https://olares.sh | bash +``` + +## 环境变量参考 + +以下列出了安装脚本所支持的环境变量及其默认值、可选值和说明。请根据具体需求进行配置。 + +### `CLOUDFLARE_ENABLE` +指定是否启用 Cloudflare 代理。 +- **可选值**： + - `0`（禁用） + - `1`（启用） +- **默认值**：`0`（禁用） + +### `DID_GATE_URL` +指定 DID 网关服务的地址。 +- **可选值**： + - `https://did-gate-v3.bttcdn.com` + - `https://did-gate-v3.api.jointerminus.cn/`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`https://did-gate-v3.bttcdn.com/` + +### `FIREBASE_PUSH_URL` +指定 Firebase 推送服务的地址。 +- **可选值**： + - `https://firebase-push-test.bttcdn.com/v1/api/push` + - `https://firebase-push-test.api.jointerminus.cn/v1/api/push`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`https://firebase-push-test.bttcdn.com/v1/api/push` + +### `FRP_AUTH_METHOD` +设置 FRP 的认证方式。 +- **可选值**： + - `jws` + - `token`（需要设置 `FRP_AUTH_TOKEN`） + - *（空字符串）* —— 不使用认证 +- **默认值**：`jws` + +### `FRP_AUTH_TOKEN` +当 `FRP_AUTH_METHOD=token` 时，用于指定服务器通信所需的 Token。 +- **可选值**：任意非空字符串 +- **默认值**：无 + +### `FRP_ENABLE` +指定是否启用 FRP 内网穿透。如果使用自定义 FRP 服务器，还需额外设置相关变量。 +- **可选值**： + - `0`（禁用） + - `1`（启用） +- **默认值**：`0`（禁用） + +### `FRP_LIST_URL` +指定 Olares FRP 信息服务的地址。 +- **可选值**： + - `https://terminus-frp.snowinning.com` + - `https://terminus-frp.api.jointerminus.cn`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`https://terminus-frp.snowinning.com` + +### `FRP_PORT` +设置 FRP 服务端监听端口。 +- **可选值**：整数范围 `1～65535` +- **默认值**：未设置或设为 `0` 时默认为 `7000` + +### `JUICEFS` +随 Olares 一起安装 [JuiceFS](https://juicefs.com/)。 +- **可选值**：`1` +- **默认值**：无（若不设置则不安装 JuiceFS） + +### `KUBE_TYPE` +指定要使用的 Kubernetes 发行版。 +- **可选值**： + - `k8s`（完整的 Kubernetes） + - `k3s`（Kubernetes 的轻量级发行版） +- **默认值**：`k3s` + +### `LOCAL_GPU_ENABLE` +指定是否启用 GPU 并安装相关驱动。 +- **可选值**： + - `0`（禁用） + - `1`（启用） +- **默认值**：`0`（禁用） + +### `LOCAL_GPU_SHARE` +指定是否启用 GPU 共享功能。仅在已启用 GPU 时生效。 +- **可选值**： + - `0`（禁用） + - `1`（启用） +- **默认值**：`0`（禁用） + +### `MARKET_PROVIDER` +指定应用市场（Market）后端服务所使用的域名，可根据网络环境选择合适的域名以优化访问速度。 +- **可选值**： + - `appstore-server-prod.bttcdn.com` + - `appstore-china-server-prod.api.jointerminus.cn`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`appstore-server-prod.bttcdn.com` + +### `NVIDIA_CONTAINER_REPO_MIRROR` +配置 `nvidia-container-toolkit` 的 APT 安装镜像源。 +- **可选值**： + - `nvidia.github.io` + - `mirrors.ustc.edu.cn`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`nvidia.github.io` + +### `OLARES_SPACE_URL` +指定 Olares Space 服务的地址。 +- **可选值**： + - `https://cloud-api.bttcdn.com/` + - `https://cloud-api.api.jointerminus.cn/`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`https://cloud-api.bttcdn.com/` + +### `PREINSTALL` +仅执行预安装阶段（系统依赖配置），不进行完整的 Olares 安装。 +- **可选值**：`1` +- **默认值**：无（若不设置则执行完整安装） + +### `PUBLICLY_ACCESSIBLE` +明确指定该机器可以在互联网上公开访问，同时不设置反向代理。 +- **可选值**： + - `0` (否) + - `1` (是) +- **默认值**: `0` + +### `REGISTRY_MIRRORS` +设置 Docker 镜像加速地址。 +- **可选值**：`https://mirrors.joinolares.cn` 或其他镜像源地址 +- **默认值**：`https://registry-1.docker.io` + +### `TAILSCALE_CONTROLPLANE_URL` +指定 Olares Tailscale 控制平面（control-plane）服务的地址。 +- **可选值**： + - `https://controlplane.snowinning.com` + - `https://controlplane.api.jointerminus.cn`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`https://controlplane.snowinning.com` + +### `TERMINUS_CERT_SERVICE_API` +指定 Olares HTTPS 证书服务的地址。 +- **可选值**： + - `https://terminus-cert.snowinning.com` + - `https://terminus-cert.api.jointerminus.cn`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`https://terminus-cert.snowinning.com` + +### `TERMINUS_DNS_SERVICE_API` +指定 Olares DNS 服务的地址。 +- **可选值**： + - `https://terminus-dnsop.snowinning.com` + - `https://terminus-dnsop.api.jointerminus.cn`（推荐中国大陆用户使用，连接性更好） +- **默认值**：`https://terminus-dnsop.snowinning.com` + +### `TERMINUS_IS_CLOUD_VERSION` +明确将此机器标记为云端实例（cloud instance）。 +- **可选值**：`true` +- **默认值**：无 + +### `TERMINUS_OS_DOMAINNAME` +在安装前预先设置域名，会跳过安装过程中的交互式提示。 +- **可选值**：任意有效域名 +- **默认值**：无（若不设置则会提示输入域名） + +### `TERMINUS_OS_EMAIL` +在安装前预先设置邮箱地址，会跳过安装过程中的交互式提示。 +- **可选值**：任意有效邮箱地址 +- **默认值**：无（若不设置则自动生成临时邮箱） + +### `TERMINUS_OS_PASSWORD` +在安装前预先设置密码，会跳过安装过程中的交互式提示。 +- **可选值**：6～32 个字符的有效密码 +- **默认值**：随机生成 8 位密码 + +### `TERMINUS_OS_USERNAME` +在安装前预先设置用户名，会跳过安装过程中的对应交互式提示。 +- **可选值**：任意有效用户名（长度 2～250，且不与保留关键词冲突） +- **默认值**：无（若不设置则会提示输入用户名） +- **验证规则**：保留关键词包括 `user`、`system`、`space`、`default`、`os`、`kubesphere`、`kube`、`kubekey`、`kubernetes`、`gpu`、`tapr`、`bfl`、`bytetrade`、`project`、`pod` + +### `TOKEN_MAX_AGE` +设置 Token 的最大有效时长（单位：秒）。 +- **可选值**：任意整数（单位：秒） +- **默认值**：`31536000`（365 天） \ No newline at end of file diff --git a/docs/zh/developer/install/index.md b/docs/zh/developer/install/index.md new file mode 100644 index 000000000..a96d92c50 --- /dev/null +++ b/docs/zh/developer/install/index.md @@ -0,0 +1,13 @@ +--- +description: Olares 部署的技术详解，包含系统架构、安装流程、环境配置、CLI 功能和版本管理以及更多的 Olares 安装方式。为开发者提供使用 Olares 的核心技术要点。 +--- +# Olares 安装详解 + +本章节将为你提供关于 Olares 安装的详细信息和命令参考，帮助你探索、学习并自定义 Olares 的安装。 + +- [Olares 安装概览](installation-overview.md)：从整体架构和核心组件的角度了解 Olares 的安装过程。 +- [Olares 安装流程详解](installation-process.md)：详解 Olares 安装的四个主要安装阶段。 +- [Olares Home 介绍](olares-home.md)：了解 Olares 默认安装目录的结构。 +- [Olares 环境变量](environment-variables.md)：查找合适的环境变量来自定义安装配置。 +- [Olares CLI 参考](./index.md)：使用 Olares CLI 命令行工具，自定义 Olares 安装或进行故障排查。 +- [Olares 版本说明](versioning.md)：了解 Olares 的版本号规则、版本类型、分支管理实践以及升级策略。 \ No newline at end of file diff --git a/docs/zh/developer/install/install-and-activate-olares.md b/docs/zh/developer/install/install-and-activate-olares.md new file mode 100644 index 000000000..5cce8d3f2 --- /dev/null +++ b/docs/zh/developer/install/install-and-activate-olares.md @@ -0,0 +1,20 @@ +--- +search: false +--- +## 安装并激活 Olares +:::warning 检查网络连接 +为避免激活失败，请确保你的手机和 Olares 设备连接到同一网络。 +::: + +1. 打开 LarePass，在账号激活页面点击**发现附近的 Olares**。LarePass 将列出同一网络中检测到的 Olares 实例。 +2. 选择标记为 **Container** 的 Olares 设备，点击**立即安装**。 +3. 安装完成后，点击**立即激活**。Olares 将开始激活流程，包括初始配置和网络设置。 +4. 按照屏幕提示重置 Olares 的登录密码，然后点击**完成**。 + +![使用 LarePass 激活 Olares](/images/zh/manual/get-started/activate-olares-mdns.png#bordered) + +激活完成后，LarePass 将显示 Olares 设备的桌面地址，如 `https://desktop.marvin123.olares.cn`。 + +![从浏览器访问 Olares](/images/zh/manual/get-started/access-olares-via-browser.png#bordered){width=30%} + + \ No newline at end of file diff --git a/docs/zh/developer/install/installation-overview.md b/docs/zh/developer/install/installation-overview.md new file mode 100644 index 000000000..f4a8258df --- /dev/null +++ b/docs/zh/developer/install/installation-overview.md @@ -0,0 +1,96 @@ +--- +outline: [2, 3] +description: Olares 部署的核心架构，涵盖系统原生层、容器编排曾和容器化层。深入解析 Olares 各层级之间的技术交互。 +--- +# Olares 安装概述 + +本文档从宏观的角度介绍了 Olares 的安装流程，重点介绍其整体架构和核心组件，旨在为系统管理员和开发者提供 Olares 运行原理及安装方法的基本了解。 + +## Olares 安装的三层结构 +Olares 的安装流程分为三个关键层级： + +- **原生层**：处理 Linux 系统配置与基础环境依赖安装。 +- **容器编排层**：部署 Kubernetes 集群，实现服务的自动化管理与扩展。 +- **容器化层**：启动容器化的系统核心服务和用户应用，提供最终运行时环境。 + +安装过程由命令行工具 `olares-cli` 管理。该工具负责协调所有组件的安装、配置以及生命周期管理。 + +![Install arch](/images/developer/install/olares-install.png) + +::: tip 提示 +要了解安装的详细过程，请参考 [Olares 安装流程详解](installation-process.md)文档。 +::: + +## 原生层 +Olares 的安装从原生层开始，确保底层 Linux 环境支持分布式存储、容器运行时和 Kubernetes 集群管理。 + +该层的配置涵盖核心 Linux 环境设置、文件系统初始化、容器运行时安装以及关键系统服务部署。 + +### 环境配置 + +安装首先配置基本的 Linux 安装环境，如配置域名解析系统（DNS）、安全外壳远程访问协议（SSH）、网络时间协议（NTP）等服务，以确保时间同步与远程管理。 + +同时，也会安装必要依赖，如 GNU 编译器集合（GCC）、网络工具（net-tools）等系统工具，确保运行时环境。 + +### 文件系统配置 + +文件系统（rootfs）用于存取系统核心组件与用户数据。根据部署需求，Olares 支持以下两种文件系统： + +- **LocalFS**（默认）：使用本地 Linux 磁盘进行存储，适用于无需网络共享且需要高数据吞吐量的单节点部署。 + +- **JuiceFS**：为多节点集群提供分布式文件系统。文件数据可以存储在本地安装的 MinIO 实例中，也可以存储在 Amazon S3 这一类远程存储桶中。该配置支持不同存储节点共享统一的存储视图。 + +:::tip 启用 JuiceFS +JuiceFS 和 MinIO 默认不会安装。如需启用，需在安装前设置必要的[环境变量](environment-variables.md#juicefs)或用 [olares-cli 命令](cli/prepare#选项)配合 JuiceFS 相应参数安装。 +::: + +### 容器运行时：containerd +Olares 使用轻量级容器运行时 containerd 进行容器化部署，其主要功能包括： +- **容器镜像管理**： + - 从内容分发网络（CDN）下载已打包的容器镜像 + - 在“准备”阶段将下载的镜像导入至 containerd + - 在“安装”环阶段以容器进程的方式启动镜像 +- **容器生命周期管理**：启动、停止、重启和监控容器化应用服务。 + +::: tip 兼容性问题 +如果你的机器之前安装过 containerd（比如通过 Docker 安装），可能会与 Olares 安装的 containerd 有兼容性问题。请在安装 Olares 前卸载现有的 containerd。 +::: + +### 系统守护进程：olaresd +olaresd 是系统守护进程，在后台运行，提供以下关键管理功能： +- **自动配置更新**：当系统发生变化（如 IP 地址变更）时，自动检测并调整相关配置项。 +- **远程系统管理**：根据来自 LarePass 客户端或 `olares-cli` 的命令执行远程系统操作，例如 Olares 安装和激活。 + +### CUDA 支持 +为了让本地 AI 模型和应用启用 GPU 加速，Olares 支持通过 [`olares-cli`](./cli/gpu.md) 自动检测并安装 CUDA 工具包和相关驱动程序。 + +## 容器编排层 +容器编排层通过 Kubernetes 将系统组件集成到高效的运行时环境中。 + +### Kubernetes 的角色 +Kubernetes 是容器编排层的核心，负责实现多组件服务的自动部署、运行、扩展和管理。 + +与 Docker Compose 或 Docker Swarm 等工具相比，Kubernetes 具有以下优势： +- 高可扩展性和生产级可靠性：适用于大规模集群部署和关键任务环境。 +- 丰富的社区支持：拥有活跃的社区和丰富的生态系统，可通过 Helm Charts、Operators 和自定义资源定义（CRDs）集成各种应用程序。 + +### Olares 支持的 Kubernetes 版本 +Olares 支持以下 Kubernetes 部署方式： +- **K3s**（默认）：轻量级 Kubernetes 发行版，可优化本地硬件上的资源利用效率。 +- **Kubernetes**：完整功能的 Kubernetes 发行版，适用于高级或自定义部署需求。 +- **minikube**（仅限 macOS）：设置单节点 Kubernetes 集群的工具，确保一致的功能和用户体验。 + +## 容器化层 + +在容器化层，Olares 各组件和应用协同工作提供系统完整功能。所有 Olares 组件和用户应用都在容器中运行，整个生命周期由 Kubernetes 管理。这确保了系统的高效性、稳定性和可扩展性。 + +在安装并激活 Olares 后，你就可以通过**控制面板**应用的图形界面查看正在运行的容器。 + +![控制面板中查看运行的容器](/images/developer/install/running-pods.png#bordered){width=90%} + +## 了解更多 + +- [Olares 安装流程详解](installation-process.md) +- [Olares Home 概述](olares-home.md) +- [`olares-cli` 命令行参考](../install/cli/olares-cli.md) +- [Olares 环境变量](environment-variables.md) \ No newline at end of file diff --git a/docs/zh/developer/install/installation-process.md b/docs/zh/developer/install/installation-process.md new file mode 100644 index 000000000..ac745e2d6 --- /dev/null +++ b/docs/zh/developer/install/installation-process.md @@ -0,0 +1,330 @@ +--- +outline: [2, 3] +description: Olares 部署阶段的技术细节，包括预检、下载、准备和安装四个阶段。详细说明每个安装阶段的具体实现。 +--- +# Olares 安装流程详解 +本文档从四个主要阶段详细说明 Olares 的安装流程，包括各阶段的底层命令、配置和逻辑。文档适用于希望深入了解安装过程的开发者和系统管理员。 + +## 四个安装阶段 +Olares 的安装可分为以下四个阶段： + +- **预检（Precheck）**：验证系统环境是否满足 Olares 安装的所有前置条件。 +- **下载（Download）**：获取安装所需的所有文件、依赖项和容器镜像。 +- **准备（Prepare）**：配置操作系统和系统服务，为 Kubernetes 和 Olares 组件创建运行环境。 +- **安装（Install）**：部署 Kubernetes，集成 KubeSphere，并安装 Olares 的核心服务和应用程序。 + +## 预检阶段 + +预检阶段的重点是验证系统是否满足安装 Olares 的必要条件。通过运行 `olares-cli precheck` 命令执行一系列验证检查。若在此阶段发现任何问题，需在继续安装前解决。 + +关键预检项目包括： +- 检查操作系统类型、版本号以及处理器架构是否兼容 +- 确保系统使用 `Systemd` 作为初始化进程 +- 验证 Olares 需要暴露的多个网络端口是否可用 +- 系统里是否存在与 Olares 冲突的容器运行时 + +下图是一个预检失败的示例： + + ![Precheck](/images/developer/install/precheck.png) + +在此示例中，有两项检查失败： +- Olares 所需的端口 `9100` 已被占用。 +- 系统中检测到已有容器运行时。 + +继续安装前必须解决这些问题。 + +## 下载阶段 + +下载阶段会下载 Olares 安装所需的 Wizard 文件、系统依赖组件和容器镜像。 + +### 下载 Wizard 文件 + +Wizard 文件是一个元数据包，包含所有 Olares 组件的下载链接和配置信息。Wizard 文件是此阶段首个被获取的文件，为后续的下载提供了关键信息。 + +Wizard 文件会被默认解压存储至 `$HOME/.olares/versions/` 目录。 + +其中： +- `$HOME/.olares` 是 Olares 的基础安装目录， +- `` 是 Olares 版本号，如示例中的 `1.12.0-20241215`。 + +:::details 脚本输出示例 +```bash +➜ ~ ./install.sh +the KUBE_TYPE env var is not set, defaulting to "k3s" +olares-cli already installed and is the expected version + +downloading installation wizard... + +current: root +2024-12-17T18:01:19.501+0800 [Job] [Download Installation Wizard] start ... +2024-12-17T18:01:19.501+0800 [Module] GreetingsModule +Greetings, Olares +2024-12-17T18:01:19.502+0800 [A] ubuntu: Greetings success (611.77µs) +2024-12-17T18:01:19.502+0800 [Module] DownloadInstallWizard +/home/keven/.olares/versions/v1.12.0-20241215/.env +/home/keven/.olares/versions/v1.12.0-20241215/wizard/config/account/Chart.yaml +``` +::: +### 下载安装所需组件与容器镜像 +Wizard 下载完成后，脚本会下载 Olares 所需的所有依赖组件和容器镜像。保存路径如下： +- 依赖包：`$HOME/.olares/pkg` +- 容器镜像：`$HOME/.olares/image` + +这种存储结构支持在多个版本之间复用稳定组件，避免重复下载。 + +:::details **脚本输出示例** +```bash +downloading installation packages... + +current: root +2024-12-17T19:41:36.847+0800 [Job] [Download Installation Package] start ... +2024-12-17T19:41:36.847+0800 [Module] GreetingsModule +Greetings, Olares +2024-12-17T19:41:36.848+0800 [A] ubuntu: Greetings success (512.711µs) +2024-12-17T19:41:36.848+0800 [Module] GenerateOlaresUninstallScript +2024-12-17T19:41:36.879+0800 [A] LocalHost: GenerateOlaresUninstallScript success (31.279866ms) +2024-12-17T19:41:36.879+0800 [Module] PackageDownloadModule +2024-12-17T19:41:36.879+0800 checking local cache ... +2024-12-17T19:41:44.614+0800 5 out of 177 files need to be downloaded +2024-12-17T19:41:44.615+0800 (1/5) downloading package olaresd, file: olaresd-v0.0.50.tar.gz +2024-12-17T19:41:51.814+0800 (2/5) downloading image calico/kube-controllers:v3.23.2, file: 521564c4b60ae73c78899b7b40ae655e.tar.gz +... +``` +::: +## 准备阶段 + +准备阶段配置操作系统环境，以支持 Kubernetes、容器镜像和 Olares 系统服务。 + +此阶段包括以下主要任务： +- 配置系统 +- 配置容器运行时 +- 安装系统守护进程 + +### 配置系统 + +安装脚本会配置 Linux 环境以满足 Olares 的要求，这些配置包括： + +- 调整 DNS、NTP 和 SSH 服务，确保网络功能和时间同步正常。 +- 通过 `apt` 安装基本依赖（如 curl、net-tools、gcc、make）。 + +:::details 脚本输出示例 +```bash +preparing installation environment... + +current: root +2024-12-17T19:46:39.517+0800 [Job] [Prepare the System Environment] start ... +2024-12-17T19:46:39.517+0800 [Module] PreCheckOs +2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckSupport success (29.999µs) +2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckPortsBindable success (144.035µs) +2024-12-17T19:46:39.517+0800 [A] LocalHost: PreCheckNoConflictingContainerd success (31.009µs) +2024-12-17T19:46:39.517+0800 [A] ubuntu: PatchAppArmor skipped (7.677µs) +2024-12-17T19:46:39.517+0800 [A] ubuntu: RaspbianCheck success (5.796µs) +2024-12-17T19:46:39.517+0800 [A] ubuntu: CorrectHostname success (5.363µs) +nameserver +nameserver +2024-12-17T19:46:41.921+0800 [A] ubuntu: DisableLocalDNS success (2.40336625s) +2024-12-17T19:46:41.921+0800 [INFO] installing and configuring OS dependencies ... +2024-12-17T19:46:41.921+0800 [Module] InstallDeps +Hit:1 http://security.ubuntu.com/ubuntu jammy-security InRelease +Hit:2 https://download.docker.com/linux/ubuntu jammy InRelease +Hit:3 http://hk.archive.ubuntu.com/ubuntu jammy InRelease +... +``` +::: +### 配置容器运行时 +容器运行时是运行容器化应用程序的关键组件。在这一步中，安装脚本将： +- 安装并启动之前下载的依赖组件 +- 在系统上安装 containerd 并启动服务 +- 将下载好的容器镜像导入至 containerd + +:::details 脚本输出示例 +```bash +2024-12-17T19:47:37.510+0800 [Module] InstallContainerModule(k3s) +2024-12-17T19:47:37.518+0800 [A] ubuntu: ZfsMountReset skipped (7.321811ms) +2024-12-17T19:47:37.525+0800 [A] ubuntu: CreateZfsMount skipped (7.322591ms) +2024-12-17T19:47:38.188+0800 [A] ubuntu: SyncContainerd success (662.643982ms) +2024-12-17T19:47:38.368+0800 [A] ubuntu: SyncCrictlBinaries success (179.758334ms) +2024-12-17T19:47:38.399+0800 [A] ubuntu: GenerateContainerdService success (31.410118ms) +2024-12-17T19:47:38.451+0800 [A] ubuntu: GenerateContainerdConfig success (52.047108ms) +2024-12-17T19:47:38.505+0800 [A] ubuntu: GenerateCrictlConfig success (53.760209ms) +2024-12-17T19:47:38.857+0800 [A] ubuntu: EnableContainerd success (352.128078ms) +2024-12-17T19:47:38.857+0800 [Module] PreloadImages +2024-12-17T19:47:41.665+0800 (1/145) imported image: rancher/mirrored-pause:3.6, time: 194.363948ms +... +``` +::: +### 安装系统守护进程 +接着是安装并启动 Olares 系统守护进程 olaresd，用于监控系统并自动执行维护任务。 + +:::details 脚本输出示例 +```bash +024-12-17T19:52:31.862+0800 [A] ubuntu: GenerateOlaresdEnv success (23.829684ms) +2024-12-17T19:52:31.862+0800 template OlaresdService result: [Unit] +Description=olaresd +After=network.target +StartLimitIntervalSec=0 + +[Service] +User=root +EnvironmentFile=/etc/systemd/system/olaresd.service.env +ExecStart=/usr/local/bin/olaresd +RestartSec=10s +LimitNOFILE=40000 +Restart=always + +[Install] +WantedBy=multi-user.target + +2024-12-17T19:52:31.885+0800 [A] ubuntu: GenerateOlaresdService success (23.050958ms) +2024-12-17T19:52:32.033+0800 [A] ubuntu: EnableOlaresdService success (147.987242ms) +... +``` +::: +## 安装阶段 +安装阶段将所有组件整合起来，并完成最终环境配置。 + +在此阶段，脚本会执行以下关键任务： +- 部署 Kubernetes。 +- 集成 KubeSphere，实现云原生管理与可观测性。 +- 配置 Olares 账户。 +- 部署并启动内置应用和服务。 + +### 部署 Kubernetes + +Kubernetes 是 Olares 系统的核心调度组件。在此步骤中，安装脚本会执行以下操作： +1. 启动 etcd 数据库。 +2. 启动并配置 K3s。 +3. 安装用于集群网络通信的容器网络界面（CNI） 插件。 +4. 将 `kubeconfig` 文件复制到当前用户目录，以便通过 `kubectl` 与集群进行交互。 + +由于 K3s 轻量且易用，Olares 默认使用它作为 Kubernetes 的发行版。如果你有高级或自定义的配置需求，也可以选择安装完整的 Kubernetes。 + +在 macOS 环境下，脚本会使用 minikube 部署集群，并跳过上述步骤。 + +:::details 脚本输出示例 +```bash +[certs] Generating "ca" certificate and key +[certs] admin-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16] +[certs] member-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16] +[certs] node-ubuntu serving cert is signed for DNS names [etcd etcd.kube-system etcd.kube-system.svc etcd.kube-system.svc.cluster.local lb.kubesphere.local localhost ubuntu] and IPs [127.0.0.1 ::1 192.168.1.16] +2024-12-17T19:52:36.957+0800 [A] LocalHost: GenerateETCDCerts success (263.237575ms) +2024-12-17T19:52:37.263+0800 [A] ubuntu: SyncCertsFile success (306.213676ms) +2024-12-17T19:52:37.264+0800 [A] ubuntu: SyncCertsFileToMaster skipped (20.351µs) +2024-12-17T19:52:37.264+0800 [Module] InstallETCDBinaryModule +2024-12-17T19:52:37.698+0800 [A] ubuntu: InstallETCDBinary success (434.014395ms) +2024-12-17T19:52:37.728+0800 [A] ubuntu: GenerateETCDService success (30.732882ms) +2024-12-17T19:52:37.728+0800 [A] ubuntu: GenerateAccessAddress success (23.491µs) +2024-12-17T19:52:37.728+0800 [Module] ETCDConfigureModule +2024-12-17T19:52:37.728+0800 [A] ubuntu: ExistETCDHealthCheck skipped (9.903µs) +2024-12-17T19:52:37.753+0800 [A] ubuntu: GenerateETCDConfig success (24.125665ms) +2024-12-17T19:52:37.773+0800 [A] ubuntu: AllRefreshETCDConfig success (20.321235ms) +2024-12-17T19:52:40.048+0800 [A] ubuntu: RestartETCD success (2.274541565s) +2024-12-17T19:52:40.068+0800 [A] ubuntu: AllETCDNodeHealthCheck success (20.251062ms) +2024-12-17T19:52:40.094+0800 [A] ubuntu: RefreshETCDConfigToExist success (26.207599ms) +2024-12-17T19:52:40.129+0800 [A] ubuntu: AllETCDNodeHealthCheck success (34.462881ms) +2024-12-17T19:52:40.129+0800 [Module] ETCDBackupModule +2024-12-17T19:52:40.185+0800 [A] ubuntu: BackupETCD success (56.639923ms) +2024-12-17T19:52:40.230+0800 [A] ubuntu: GenerateBackupETCDService success (44.727929ms) +2024-12-17T19:52:40.273+0800 [A] ubuntu: GenerateBackupETCDTimer success (42.839457ms) +2024-12-17T19:52:40.396+0800 [A] ubuntu: EnableBackupETCDService success (122.621074ms) +2024-12-17T19:52:40.396+0800 [Module] InstallKubeBinariesModule +2024-12-17T19:52:41.188+0800 [A] ubuntu: SyncKubeBinary(k3s) success (791.866964ms) +2024-12-17T19:52:41.218+0800 [A] ubuntu: GenerateK3sKillAllScript success (30.442837ms) +2024-12-17T19:52:41.253+0800 [A] ubuntu: GenerateK3sUninstallScript success (34.802683ms) +2024-12-17T19:52:41.268+0800 [A] ubuntu: ChmodScript(k3s) success (14.640733ms) +2024-12-17T19:52:41.268+0800 [Module] K3sInitClusterModule +2024-12-17T19:52:41.334+0800 [A] ubuntu: GenerateK3sService success (66.556896ms) +2024-12-17T19:52:41.379+0800 [A] ubuntu: GenerateK3sServiceEnv success (44.492752ms) +2024-12-17T19:52:41.414+0800 [A] ubuntu: GenerateK3sRegistryConfig success (34.814475ms) +2024-12-17T19:52:46.511+0800 [A] ubuntu: EnableK3sService success (5.097800474s) +2024-12-17T19:52:46.572+0800 [A] ubuntu: CopyKubeConfig success (60.33887ms) +... +``` +::: +### 集成 KubeSphere + +Olares 会基于 Kubernetes 安装 KubeSphere，以增强系统的管理和可观测性。主要特性包括： + +- 系统监控与告警 +- 资源和工作区管理 +- 命名空间和自定义资源定义（CRD）管理 + +### 配置账户 +Olares ID 在 LarePass 应用中创建。在这一步中，安装脚本会提示输入以下信息，以便后续使用 LarePass 激活 Olares： + +- **Olares 域名**: Olares 提供默认域名 `olares.com` 和 `olares.cn` 。如果你已将自定义域名添加到 Olares Space，也可以在此步骤中输入自定义域名。 +- **Olares ID**: 输入 Olares ID 中的用户名部分。 + +完成此步骤后，系统会为你创建一个用于登录 Olares 的账户，并完成相关的访问和权限配置。 + +:::details 脚本输出示例 +```bash +Enter the domain name ( olares.cn by default ): +2024-12-17T20:58:15.690+0800 using Domain Name: olares.cn + +Enter the Olares ID (which you registered in the LarePass app): marvin113 +2024-12-17T20:58:52.584+0800 using Olares Local Name: marvin113 +2024-12-17T20:58:52.584+0800 using Olares ID: marvin113@olares.com +2024-12-17T20:58:52.584+0800 using password: 2uO5PZ2X +``` +::: +### 安装系统应用 +安装的最后一步会通过 Helm 部署 Olares 系统的核心服务与用户应用： +- **核心系统服务**（在 `os-system` 命名空间中）：包含备份（Velero）、存储（OpenEBS）、Redis、Nats、MinIO 等关键组件。 +- **用户应用**（在`user-space-xxx` 命名空间中）：包含文件管理器、桌面、设置等系统应用。 + +安装过程中，日志中会显示如 `[helm] app installed success` 以及一系列 `xxx created` 的提示，表示对应的 Helm Chart 或 Kubernetes 资源安装成功。 + +:::details 脚本输出示例 +```bash +2024-12-17T19:53:18.382+0800 [A] ubuntu: InitKsNamespace success (2.678362348s) +2024-12-17T19:53:18.382+0800 [Module] DeploySnapshotController +customresourcedefinition.apiextensions.k8s.io/volumesnapshotclasses.snapshot.storage.k8s.io created +customresourcedefinition.apiextensions.k8s.io/volumesnapshotcontents.snapshot.storage.k8s.io created +customresourcedefinition.apiextensions.k8s.io/volumesnapshots.snapshot.storage.k8s.io created +2024-12-17T19:53:18.924+0800 [helm] app installed success {"NAME": "snapshot-controller", "LAST DEPLOYED": "Tue Dec 17 19:53:18 2024", "NAMESPACE": "kube-system", "STATUS": "deployed", "REVISION": 1} +2024-12-17T19:53:18.924+0800 [A] ubuntu: CreateSnapshotController success (541.656132ms) +2024-12-17T19:53:18.924+0800 [Module] DeployRedis +secret/redis-secret created +2024-12-17T19:53:19.057+0800 [A] ubuntu: CreateRedisSecret success (133.123121ms) +2024-12-17T19:53:19.189+0800 [A] ubuntu: BackupRedisManifests success (132.045425ms) +2024-12-17T19:53:19.339+0800 [A] ubuntu: DeployRedisHA success (149.251633ms) +local (default) openebs.io/local Delete WaitForFirstConsumer false 31s +local (default) openebs.io/local Delete WaitForFirstConsumer false 31s +2024-12-17T19:53:19.971+0800 [helm] app installed success {"NAME": "redis", "LAST DEPLOYED": "Tue Dec 17 19:53:19 2024", "NAMESPACE": "kubesphere-system", "STATUS": "deployed", "REVISION": 1} +... +``` +::: + +### 完成安装 + +待所有组件部署成功后，脚本会输出包含激活向导页面 URL 的汇总信息： + +```bash +2024-12-17T21:00:58.086+0800 [INFO] Installation wizard is complete +2024-12-17T21:00:58.086+0800 [INFO] All done + +------------------------------------------------ + +2024-12-17T21:00:58.086+0800 Olares is running at: +2024-12-17T21:00:58.086+0800 http://192.168.1.16:30180 + +2024-12-17T21:00:58.086+0800 Open your browser and visit the above address +2024-12-17T21:00:58.086+0800 with the following credentials: + +2024-12-17T21:00:58.086+0800 Username: marvin113 +2024-12-17T21:00:58.086+0800 Password: 2uO5PZ2X +``` + +此时，执行以下操作以完成安装： +1. 打开浏览器并输入提供的 URL。 +2. 使用初始密码登录激活向导。 +3. 按照屏幕提示完成激活流程。 + +完成激活后，你就可以开始使用 Olares 了。 + +## 了解更多 + +- [`olares-cli` 命令行参考](../install/cli/olares-cli.md) +- [Olares 安装概述](installation-overview.md) +- [Olares 环境变量](environment-variables.md) \ No newline at end of file diff --git a/docs/zh/developer/install/linux-via-docker-compose.md b/docs/zh/developer/install/linux-via-docker-compose.md new file mode 100644 index 000000000..3ec7b5058 --- /dev/null +++ b/docs/zh/developer/install/linux-via-docker-compose.md @@ -0,0 +1,145 @@ +--- +outline: [2, 3] +description: 了解如何使用 Docker Compose 在 Linux 服务器上部署 Olares。本安装指南涵盖系统要求、配置、安装、激活以及容器管理的相关内容。 +--- +# 使用 Docker Compose 在 Linux 上安装 Olares +通过 Docker 可以在容器化环境中安装和运行 Olares。本文将介绍如何使用 Docker 设置 Olares、准备安装环境、完成激活过程以及管理容器生命周期。 + +::: warning 不适用于生产环境 +该部署方式仅适用于开发或测试环境。我们推荐[通过脚本方式在 Linux 上安装 Olares](/zh/manual/get-started/install-olares.md)，以获得最佳的性能与稳定性。 +::: + + + +## 系统要求 + +请确保设备满足以下配置要求： + +- CPU：4 核及以上 +- 内存：不少于 8GB 可用内存 +- 存储：建议使用 SSD，且可用磁盘空间不少于 64GB +- 支持的系统版本： + - Ubuntu 20.04 LTS 及以上 + - Debian 11 及以上 + +## 开始之前 +开始安装前，请确保： +- 系统中已安装并运行 [Docker](https://docs.docker.com/engine/install/) 和 [Docker Compose](https://docs.docker.com/compose/install/)。 +- 已知当前设备的 IP 地址。 + :::tip 查看 IP 地址 + 如需确认 IP 地址，在终端中运行以下命令： + ```bash + ip r + ``` + 找到以 `default via` 开头的行，对应默认网关和正在使用的网络接口。 + ::: +- 已通过 LarePass [创建 Olares ID](/zh/manual/get-started/create-olares-id.md) 且使用默认的 `olares.cn` 域名。 + +## 创建文件夹 +创建文件夹存储 Olares 的配置文件。例如，用如下命令创建名为 `olares-config` 的文件夹： + +```bash +mkdir ~/olares-config +cd ~/olares-config +``` +## 准备 `docker-compose.yaml` +1. 在 `olares-config` 目录中创建 `docker-compose.yaml` 文件。 +2. 根据是否启用 GPU，填入对应的内容： + :::code-group + <<< @/code-snippets/docker-compose.yaml + <<< @/code-snippets/docker-compose-GPU.yaml + ::: +3. 保存 `docker-compose.yaml` 文件。 + +## 更新 Docker 的镜像源 +添加 Olares 的镜像源，提高镜像拉取速度： +1. 打开 `/etc/docker/daemon.json` 文件。 +2. 编辑文件，加上以下内容： + + <<< @/code-snippets/docker-daemon.json +3. 重启 Docker 服务以应用更改。 + ```bash + sudo systemctl restart docker + ``` +4. 验证配置文件是否修改成功： + ```bash + docker info + ``` + 在输出的结果中，如输出结果包含如下内容，表示修改成功： + + ```bash + Registry Mirrors: + https://mirrors.joinolares.cn/ + ``` +## 设置环境变量并启动容器 + +1. 在 `olares-config` 目录，运行以下命令设置环境变量并启动容器： + ```bash + VERSION=-cn HOST_IP= docker compose up -d + ``` + - `VERSION=-cn`：指定 Olares 镜像的版本。将 `-cn` 替换为实际版本，如 `1.11.5-cn`。 + - `HOST_IP=`：指定当前主机设备的 IP 地址。将 `` 替换为实际地址。 + + 运行完成后，输出结果如下： + ```bash + [+] Running 20/20 + ✔ olaresd-proxy Pulled 67.8s + ✔ 688513194d7a Pull complete 6.8s + ✔ bfb59b82a9b6 Pull complete 6.9s + ✔ efa9d1d5d3a2 Pull complete 9.5s + ✔ a62778643d56 Pull complete 9.6s + ✔ 7c12895b777b Pull complete 9.6s + ✔ 3214acf345c0 Pull complete 13.6s + ✔ 5664b15f108b Pull complete 14.1s + ✔ 0bab15eea81d Pull complete 14.2s + ✔ 4aa0ea1413d3 Pull complete 15.0s + ✔ da7816fa955e Pull complete 15.1s + ✔ 9aee425378d2 Pull complete 15.1s + ✔ 701c983262e9 Pull complete 36.2s + ✔ 221438ca359c Pull complete 36.3s + ✔ f3d0ed3b32e0 Pull complete 36.4s + ✔ 70d5c1f325f6 Pull complete 43.2s + ✔ olares Pulled 5863.6s + ✔ 2d5815038f40 Pull complete 5759.0s + ✔ 13788179ee16 Pull complete 5831.6s + ✔ 5a9b10c3302f Pull complete 5831.7s + ``` + +2. 确认容器是否正常运行： + ```bash + docker ps + ``` + 输出结果如下： + ```bash + CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES + 28e86c473750 beclab/olaresd:proxy-v0.1.0 "/mdns-agent" About a minute ago Up About a minute olares-olaresd-proxy-1 + 5fd68a8709ad beclab/olares:1.11.5-cn "/usr/local/bin/entr…" 2 minutes ago Up About a minute 0.0.0.0:80->80/tcp... olares-olares-1 + ``` + + + +## 管理 Olares 容器 +在运行任何命令之前，请确保你位于包含 `docker-compose.yaml` 文件的目录中。 +### 停止容器 +要停止当前正在运行的容器： +```bash +docker compose stop +``` + +### 重启容器 +容器停止后，使用以下命令重启： +```bash +docker compose start +``` +容器重启后，所有服务可能需要 6–7 分钟才能完全初始化。在此时间内请耐心等待。 + +### 卸载容器 +要完全删除容器： +```bash +docker compose down +``` + + + + + diff --git a/docs/zh/developer/install/log-in-to-olares.md b/docs/zh/developer/install/log-in-to-olares.md new file mode 100644 index 000000000..8dd963747 --- /dev/null +++ b/docs/zh/developer/install/log-in-to-olares.md @@ -0,0 +1,17 @@ +--- +search: false +--- +## 登录 Olares + +1. 在登录页面输入 Olares 登录密码。 + + ![登录](/images/manual/get-started/log-in.png#bordered) +2. 系统会要求完成双重验证。你可以选择在 LarePass 上确认登录，或手动输入 6 位验证码。 + ::: info + 验证码有时效限制，请在过期前完成输入。如果验证码过期，需要重新生成。 + ::: + + ![确认登录](/images/manual/get-started/confirm-login.png#bordered) + +登录后你就会看到 Olares 桌面。🎉 + diff --git a/docs/zh/developer/install/lxc.md b/docs/zh/developer/install/lxc.md new file mode 100644 index 000000000..74e6f4670 --- /dev/null +++ b/docs/zh/developer/install/lxc.md @@ -0,0 +1,152 @@ +--- +description: 在 LXC 容器环境中安装配置 Olares 的完整步骤，包括容器设置、系统要求和激活方法。 +--- +# 在 Linux 容器（LXC）中安装 Olares +LXC 是一种轻量级的虚拟化技术，可以在隔离的容器中运行应用程序。在 PVE 环境下使用 LXC 部署 Olares 能够避免完整虚拟机的额外开销，提供了一种更高效的部署方式。 + +::: warning 不适用于生产环境 +该部署方式当前仍有功能限制，建议仅用于开发或测试环境。 +::: + + + +## 系统要求 +请确保设备满足以下配置要求： + +- CPU：4 核及以上 +- 内存：不少于 8GB 可用内存 +- 存储：建议使用 SSD，且可用磁盘空间不少于 64GB +- 支持的系统版本： + - PVE: 8.2.2 + - LXC 容器系统：Debian 12（既有 LXC 环境） + +:::info 版本兼容性 +虽然以上版本已经过验证，但其他版本也可能正常运行 Olares。根据你的环境可能需要进行调整。如果你在这些平台上安装时遇到任何问题，欢迎在 [GitHub](https://github.com/beclab/Olares/issues/new) 上提问。 +::: + +## 准备工作 + +- 在 PVE 主机上创建用于存储镜像和软件包的工作目录。 + + ```bash + mkdir -p /root/.olares/images /root/.olares/pkg + ``` +- `debian-12-standard_12.7-1_amd64.tar.zst` 的容器模板（CT），可从 PVE [镜像仓库](http://download.proxmox.com/images/system/)下载。 + +## 配置 LXC 环境 + +::: tip 安装至已有 LXC 容器 +如果你想要在 PVE 中已有 LXC 容器上安装 Olares，请直接到第二步更新 LXC 配置。要记得更新对应的容器 ID。 +::: + +1. 使用以下命令创建 LXC 容器： + + ::: tip 指定唯一容器 ID + 要创建容器，必须分配一个唯一的**容器 ID**。此处以 `16553` 为例，你可以将其替换为任何可用的数字 ID，并在所有相关命令和配置中更新此 ID。 + ::: + + ```bash{2} + export ROOTPASS=123456 + pct create 16553 /var/lib/vz/template/cache/debian-12-standard_12.7-1_amd64.tar.zst \ + --hostname olares \ + --ostype ubuntu \ + --cores 4 \ + --memory 10240 \ + --swap 0 \ + --net0 name=eth0,bridge=vmbr0,firewall=1,ip=dhcp,ip6=dhcp,type=veth \ + --rootfs local-lvm:80 \ + --unprivileged 0 \ + --ignore-unpack-errors \ + --mp0 "/root/.olares/images,mp=/root/.olares/images" \ + --mp1 "/root/.olares/pkg,mp=/root/.olares/pkg" \ + --password="$ROOTPASS" + +2. 修改 LXC 配置。 + + a. 打开配置文件: + + ```bash + nano /etc/pve/lxc/16553.conf + ``` + + b. 复制并粘贴以下配置到文件中: + + ```bash + # 基础配置 + arch: amd64 + cores: 4 + hostname: olares + memory: 10240 + net0: name=eth0,bridge=vmbr0,firewall=1,hwaddr=BC:24:11:13:05:7C,ip=dhcp,ip6=dhcp,type=veth + ostype: debian + rootfs: local-lvm:vm-16553-disk-0,size=80G + + # 存储配置 + mp0: /root/.olares/images,mp=/root/.olares/images + mp1: /root/.olares/pkg,mp=/root/.olares/pkg + + # 权限配置 + lxc.apparmor.profile: unconfined + lxc.cgroup.devices.allow: a + lxc.cap.drop: + lxc.mount.auto: "proc sys cgroup:mixed" + ``` + + c. 保存并退出编辑界面。 + +3. 在 PVE 主机上启用 IP 虚拟服务器 （IPVS) 模块： + + ```bash + sudo modprobe ip_vs + sudo modprobe ip_vs_rr + sudo modprobe ip_vs_wrr + sudo modprobe ip_vs_sh + sudo modprobe overlay + ``` +4. 启动并配置 LXC 容器。 + + ```bash + # 启动容器 + pct start 16553 + + # 进入容器 + pct enter 16553 + + # 创建缺失的目录 + mkdir -p /lib/modules + + # 更新 PATH 环境变量 + echo 'export PATH="/usr/local/bin:$PATH"' >> /root/.bashrc + source ~/.bashrc + + # 退出 LXC + exit + ``` + +5. 将 PVE 依赖项复制到 LXC 容器。 + + ```bash + # 将内核配置从 PVE 主机复制到 LXC 容器 + pct push 16553 /boot/config-$(uname -r) /boot/config-$(uname -r) + + # 打包并复制内核模块目录 + tar cvf /lib/modules/6.8.4-2-pve.tar.gz /lib/modules/6.8.4-2-pve + pct push 16553 /lib/modules/6.8.4-2-pve.tar.gz /lib/modules/6.8.4-2-pve.tar.gz + + # 在 LXC 容器内解压内核模块文件 + pct enter 16553 + cd /lib/modules + tar xvf /lib/modules/6.8.4-2-pve.tar.gz -C / + ``` + +## 安装 Olares + +在 LXC 容器中运行以下安装命令： + + + + + + + + \ No newline at end of file diff --git a/docs/zh/developer/install/mac-via-docker-image.md b/docs/zh/developer/install/mac-via-docker-image.md new file mode 100644 index 000000000..e6fbbc50f --- /dev/null +++ b/docs/zh/developer/install/mac-via-docker-image.md @@ -0,0 +1,120 @@ +--- +outline: [2, 3] +description: 了解如何在 Mac 上使用 Docker 容器部署运行 Olares 的完整步骤，包括镜像配置和容器设置说明。 +--- +# 使用 Docker 镜像在 Mac 上安装 Olares + +你可以通过 Docker 可以在容器化环境中安装和运行 Olares。本文将带你了解：如何使用 Docker 设置 Olares，准备安装环境，完成激活流程，并管理容器的生命周期。 + +:::warning 不适用于生产环境 +Mac 版 Olares 目前存在以下限制： +- 不支持分布式存储 +- 无法添加本地节点 + +建议仅用于开发或测试环境。 +::: + + + +## 系统要求 +Mac 设备需满足以下条件： +- 处理器架构：AMD64 或 ARM64 +- 内存：可用内存 8 GB 及以上 +- 存储空间：可用磁盘空间 90 GB 及以上 +- MacOS 版本：Monterey（12）及以上 + +## 开始之前 +开始安装前，请确保： +- 系统中已安装并运行 [Docker](https://docs.docker.com/engine/install/)。 +- 已知当前设备的 IP 地址。 + ::: tip 查看 IP 地址 + 要查看 Mac 的 IP 地址，可以使用两种方式: + - 使用图形界面：打开**系统设置**（或**系统偏好设置**）> **网络**，在当前活动的网络连接中查看详细信息。 + - 使用命令行：打开终端窗口，Wi-Fi 网络输入 `ipconfig getifaddr en0`，有线网络输入 `ipconfig getifaddr en1`。 + ::: +- 已通过 LarePass [创建 Olares ID](/zh/manual/get-started/create-olares-id.md) 且使用默认的 `olares.cn` 域名。 + +## 运行 `olaresd-proxy` +::: tip 确认 Mac 芯片 +如果你不确定 Mac 所使用的芯片，请点击苹果菜单并选择**关于本机**，查看芯片类型。 +::: + + + + + + +## 更新 Docker 的镜像源 +添加 Olares 的镜像源，提高镜像拉取速度。以 Docker Desktop 为例： +1. 打开 Docker Desktop，选择 **Settings** > **Docker Engine**。 +2. 修改 Docker daemon 的 `json` 文件，添加镜像源： + ```json{9-11} + { + "builder": { + "gc": { + "defaultKeepStorage": "20GB", + "enabled": true + } + }, + "experimental": false, + "registry-mirrors": [ + "https://mirrors.joinolares.cn" + ] + } + ``` +3. 点击 **Apply & restart** 保存变更。 + +## 使用 Docker CLI 运行 Olares + +执行以下命令来拉取 Olares 的镜像。 + +将 `` 替换为设备的 IP 地址，将 `-cn` 替换为想要使用的 Olares 版本： + +```bash{2,9} +docker run -d --privileged -v oic-data:/var \ + -e HOST_IP= \ + -p 80:80 \ + -p 443:443 \ + -p 30180:30180 \ + -p 18088:18088 \ + -p 41641:41641/udp \ + --name oic \ + beclab/olares:-cn +``` +其中： + - `-d`：以分离模式（detached mode）启动容器，允许其在后台运行。 + - `--privileged`：授予容器完整的系统权限。 + - `-v oic-data:/var`：将 Docker 数据卷（`oic-data`）挂载到容器内的 `/var` 目录以持久化数据。 + - `-e HOST_IP=`：设置主机设备的 IP 地址作为环境变量 + - `-p 80:80`：将主机的 `80` 端口映射到容器的 `80` 端口。 + - `-p 443:443`：将主机的 `443` 端口映射到容器的 4`43` 端口。 + - `-p 30180:30180`：将主机的 `30180` 端口映射到容器的 `30180` 端口。 + - `-p 18088:18088`：将宿主机的 `18088` 端口映射到容器的 `18088` 端口。 + - `-p 41641:41641/udp`：将宿主机的 `41641` UDP 端口映射到容器的 `41641` UDP 端口。 + - `--name oic`：将容器命名为 `oic`（Olares in container）方便后续引用。 + - `beclab/olares:-cn`：指定 Olares Docker 镜像及版本，例如`beclab/olares:1.11.5-cn`。 + +容器启动后，你会看到一个容器 ID。 +:::warning 请勿添加 `--rm` 参数 +`--rm` 参数会在容器停止后自动删除容器。如果发生这种情况，将无法重新启动容器，必须重新安装 Olares 才能再次运行。不使用此参数可以在停止后保留容器，让你能够通过 docker start 命令恢复运行。 +::: + + + + + + diff --git a/docs/zh/developer/install/mac.md b/docs/zh/developer/install/mac.md new file mode 100644 index 000000000..2ca0f7323 --- /dev/null +++ b/docs/zh/developer/install/mac.md @@ -0,0 +1,65 @@ +--- +description: 在 Mac 系统上安装配置 Olares 的完整步骤，包括环境准备、安装过程和系统激活。 +--- +# 在 Mac 上使用脚本安装 Olares +本文介绍如何在 Mac 上使用脚本安装 Olares。 + +::: warning 不适用于生产环境 +Mac 版 Olares 目前存在以下限制： +- 不支持分布式存储 +- 无法添加本地节点 + +建议仅用于开发或测试环境。 +::: + + + +## 系统要求 +Mac 设备需满足以下条件： +- 处理器架构：X86-64 或 ARM64 +- 内存：可用内存 8 GB 及以上 +- 存储空间：可用磁盘空间 90 GB 及以上 +- MacOS 版本：Monterey（12）及以上 + +## 前置准备 +请确保已安装以下软件： +- [Docker Desktop](https://www.docker.com/products/docker-desktop/) +- [MiniKube](https://minikube.sigs.k8s.io/docs/start/?arch=%2Fmacos%2Farm64%2Fstable%2Fhomebrew) + ::: tip + 推荐通过 `homebrew` 安装 minikube。 + ::: + +## 配置系统环境 +1. 打开 Docker Desktop，进入 **Settings** > **Resources**，按以下要求配置资源： + - **CPU limit**：至少设置为 4 核 + - **Memory limit**：至少设置为 9 GB + - **Virtual disk limit**：至少设置为 80 GB + + ![更新资源配置示例](/images/manual/get-started/docker-resources-settings.png#bordered) +2. 点击 **Apply & restart** 使配置生效。 +## 安装 Olares +在终端中运行以下命令： + + +## 配置 Wizard +在安装过程结束时，你需要提供下列信息： +1. 检查 Mac 的 IP 地址（例如，`192.168.x.x`）。 + + 如果自动获取的 IP 地址正确，请按 `Y` 确认。如果需要修改，请按 `R` 并输入正确的地址。 + ::: tip 查看 IP 地址 + 要查看 Mac 的 IP 地址，可以使用两种方式: + - 使用图形界面：打开**系统设置**（或**系统偏好设置**）> **网络**，在当前活动的网络连接中查看详细信息。 + - 使用命令行：打开终端窗口，Wi-Fi 网络输入 `ipconfig getifaddr en0`，有线网络输入 `ipconfig getifaddr en1`。 + ::: + +2. 如果你的 Olares ID 为 `alice123@olares.cn`，输入 `alice123` 即可。 + + ![输入 Olares ID](/images/zh/manual/get-started/enter-olares-id.png) + + + + + + + + \ No newline at end of file diff --git a/docs/zh/developer/install/manage-olares-container.md b/docs/zh/developer/install/manage-olares-container.md new file mode 100644 index 000000000..b2c2009e3 --- /dev/null +++ b/docs/zh/developer/install/manage-olares-container.md @@ -0,0 +1,25 @@ +--- +search: false +--- +## 管理 Olares 容器 + +### 停止容器 +要停止运行中的容器： +```bash +docker stop oic +``` + +### 重启容器 +容器停止后，使用以下命令重启： +```bash +docker start oic +``` +容器重启后，所有服务可能需要 6–7 分钟才能完全初始化。在此时间内请耐心等待。 + +### 卸载容器 +要完全移除容器及其关联数据： +```bash +docker stop oic +docker rm oic +docker volume rm oic-data +``` \ No newline at end of file diff --git a/docs/zh/developer/install/olares-home.md b/docs/zh/developer/install/olares-home.md new file mode 100644 index 000000000..a944b5b05 --- /dev/null +++ b/docs/zh/developer/install/olares-home.md @@ -0,0 +1,66 @@ +--- +description: Olares Home 目录的内部结构，用于组织镜像、日志、依赖项和版本管理。详细介绍默认安装目录的架构设计。 +--- +# Olares Home + +Olares Home 是 Olares 的默认安装目录，用于存储镜像、日志、依赖组件以及版本管理数据。本文将带你了解 Olares Home 的结构，进一步 Olares 安装过程。 + +## 路径及设置 + +默认情况下，Olares Home 位于 `~/.olares`。你可以执行 `olares-cli` 命令时配合 `--base-dir` 选项更改其位置。例如： + +```bash +# 指定所有下载组件的存储目录 +olares-cli download component --base-dir /custom/path +``` + +## 目录结构 + +Olares Home 目录结构如下： + +``` +./olares +├── images # 存放下载的镜像文件 +│ ├── {image-file}.tar.gz +│ └── {image-file}.tar.gz +├── logs # 存放所有日志 +├── pkg # 存放下载的系统依赖组件 +│ ├── cni # K8s 的网络插件 +│ ├── components # 存放与 K8s 无关的 Olaers 基础软件依赖， +│ │ 如 olaresd/JuiceFS/Redis 等 +│ ├── containerd # CRI 运行时 +│ ├── crictl # CRI 命令行工具 +│ ├── etcd # K8s 的持久化数据库 +│ ├── helm # K8s 的 app 管理命令行工具 +│ ├── kube # 存放 K8s 的核心程序，如 kubeadm/kubelet/k3s +│ └── runc # OCI 运行时 +└── versions # 存放不同的 Olares 版本 + ├── v1.10.0-20241001 + │ ├── cli + │ ├── deploy + │ ├── files + │ ├── images + │ ├── logs # 存放该 Olares 版本相关的日志 + │ │ ├── install.log + │ │ └── uninstall.log + │ └── wizard # 存放 Olares 自带的系统及用户应用 Helm chart + └── v1.10.0-20240930 + ├── cli + ├── deploy + ├── files + ├── images + ├── logs + │ ├── install.log + │ └── uninstall.log + └── wizard +``` + +Olares Home 的结构设计旨在优化文件管理、版本控制和资源共享，其优势包括： +- 不同版本的 Olares 存储在 `versions` 目录下，版本相关的所有文件和日志都集中在对应的子目录中。 +- 一台机器上只能运行一个 Olares 实例，避免版本冲突。 +- 不同版本会共享 `images` 和 `pkg` 目录下的文件，避免重复下载，节省磁盘空间。 + +## 了解更多 +- [`olares-cli` 命令行参考](../install/cli/olares-cli.md) +- [Olares 安装流程详解](installation-process.md) +- [Olares 环境变量](environment-variables.md) diff --git a/docs/zh/developer/install/pve.md b/docs/zh/developer/install/pve.md new file mode 100644 index 000000000..dbb71188f --- /dev/null +++ b/docs/zh/developer/install/pve.md @@ -0,0 +1,35 @@ +--- +description: 在 PVE 虚拟化平台上安装配置 Olares 的完整步骤，包括系统要求、安装命令和激活过程。 +--- +# 在 PVE 上安装 Olares +Proxmox 虚拟环境（PVE）是一个基于 Debian Linux 的开源虚拟化平台。本文将介绍如何在 PVE 环境中安装 Olares。 + +::: warning 不适用于生产环境 +该部署方式当前仍有功能限制，建议仅用于开发或测试环境。 +::: + + + +## 系统要求 +请确保设备满足以下配置要求： + +- CPU：4 核及以上 +- 内存：不少于 8GB 可用内存 +- 存储：建议使用 SSD，且可用磁盘空间不少于 64GB +- 支持的系统版本：PVE 8.2.2 + +:::info 版本兼容性 +虽然以上版本已经过验证，但其他版本也可能正常运行 Olares。根据你的环境可能需要进行调整。如果你在这些平台安装时遇到任何问题，欢迎在 [GitHub](https://github.com/beclab/Olares/issues/new) 上提问。 +::: + +## 安装 Olares + +在 PVE 命令行中，执行以下命令： + + + + + + + + \ No newline at end of file diff --git a/docs/zh/developer/install/raspberry-pi.md b/docs/zh/developer/install/raspberry-pi.md new file mode 100644 index 000000000..7c38389dd --- /dev/null +++ b/docs/zh/developer/install/raspberry-pi.md @@ -0,0 +1,42 @@ +--- +description: 使用树莓派安装配置 Olares 的完整步骤，包括硬件要求、安装命令和系统设置。 +--- +# 在树莓派上安装 Olares +本文介绍如何在树莓派设备上安装 Olares。 + +::: warning 不适用于生产环境 +该部署方式当前仍有功能限制，建议仅用于开发或测试环境。 +::: + + + +## 系统要求 +请确保树莓派设备满足以下要求： +- 硬件：树莓派 4B 或树莓派 5（8GB 内存版本） +- 操作系统：Raspbian 12 +- 存储空间：64GB（建议使用 SSD） + +## 配置环境 +1. 配置 Raspbian 环境，启用必要功能： + + ```bash + echo "$(head -1 /boot/firmware/cmdline.txt) cgroup_enable=cpuset cgroup_enable=memory cgroup_memory=1" | sudo tee /boot/firmware/cmdline.txt + + echo "kernel=kernel8.img" | sudo tee -a /boot/firmware/config.txt + ``` + +2. 重启树莓派使配置生效。 + + ```bash + sudo reboot + ``` +## 安装 Olares +执行以下命令: + + + + + + + + \ No newline at end of file diff --git a/docs/zh/developer/install/reusables.md b/docs/zh/developer/install/reusables.md new file mode 100644 index 000000000..bef152e9f --- /dev/null +++ b/docs/zh/developer/install/reusables.md @@ -0,0 +1,45 @@ +--- +search: false +--- + +```bash +curl -fsSL https://cn.olares.sh | bash - +``` + +:::tip root 用户密码 +安装过程中，可能需要输入 root 用户密码。 +::: + +:::info 安装遇到报错？ +如果安装过程中出现错误，请先执行以下命令卸载： + +```bash +olares-cli uninstall --all +``` + +卸载完成后，重新运行安装命令进行安装。 +::: + +## 配置 Wizard + +在安装 Olares 的核心服务之前，需要输入在 LarePass 中注册的 Olares ID 前缀。如果你的 Olares ID 为 `alice123@olares.cn`，输入 `alice123` 即可。 + +![输入 Olares ID](/images/zh/manual/get-started/enter-olares-id.png) + +安装完成后，屏幕将显示初始系统信息，包括向导地址和初始一次性密码。这些信息在后续激活步骤中会用到。 + +![Wizard URL](/images/manual/get-started/wizard-url-and-login-password.png) + +## 下一步：安全保存 Olares ID + +你已经准备好开始使用 Olares！在此之前，请务必确保 Olares ID 已安全备份。如果不备份，你将无法在需要时恢复 Olares ID。 + +- [备份助记词](/zh/manual/larepass/back-up-mnemonics.md) + +:::info 安装遇到问题？ +如果安装过程中遇到问题，[可以提交 GitHub Issue](https://github.com/beclab/Olares/issues/new)。提交时请提供以下信息： + +- 使用的平台或环境（如 Ubuntu、Docker、WSL 等）。 +- 安装方式（脚本安装或 Docker 镜像）。 +- 详细的错误信息（包括日志、错误提示或截图）。 + ::: diff --git a/docs/zh/developer/install/versioning.md b/docs/zh/developer/install/versioning.md new file mode 100644 index 000000000..f284adefc --- /dev/null +++ b/docs/zh/developer/install/versioning.md @@ -0,0 +1,66 @@ +--- +outline: [2, 3] +description: Olares 的版本管理系统，包括发布类型、分支策略和升级规范。详述语义化版本的实现方式和兼容性要求。 +--- +# Olares 版本说明 + +Olares 的版本管理和发布流程旨在提供清晰的版本号定义和稳定的升级路径。本文档介绍了 Olares 的版本号规则、版本类型、分支管理实践以及升级策略。 + +## 版本号规则 + +Olares 版本号主要遵循 [语义版本号规范](https://semver.org/lang/zh-CN/)，其格式为`主版本号.次版本号.修订号[-预发布版本号]`。例如，`1.11.0-rc.0` 表示 `1.11.0` 的候选版本。 + +版本顺序如下： + `1.0.0-alpha` < `1.0.0-alpha.1` < `1.0.0-alpha.beta` < `1.0.0-beta` < `1.0.0-beta.2` < `1.0.0-beta.11` < `1.0.0-rc.1` < `1.0.0` + +## 发布策略 + +Olares 提供三种类型的版本：**正式版**、**候选（RC）版**和**每日构建版（Daily Build）**。 + +### 正式版 + +正式版是经过全面测试后发布的版本，适用于生产环境。官方的一行安装命令始终默认安装最新发布的正式版。 +- **发布节奏**：每月一次 +- **示例**：`v1.10.5`、`v1.11.0`、`v1.11.1`、`v1.12.0` + +### RC 版 + +RC 版是用于测试的预发布版本。在发布正式版之前，RC 版可能会经过多次迭代，最终升级为正式版。 +- **发布节奏**：根据测试进度 +- **示例**：`v1.11.0.rc.0`、`v1.11.0.rc.1` + +### 每日构建版 + +每日构建版是每天凌晨 2 点（UTC+8）从 `main` 分支自动生成的版本，版本号中包含生成日期。这些版本反映了最新的代码更改，适用于开发和测试用途。每日构建版通常不稳定，不适合生产使用。 +- **发布节奏**：每天 +- **示例**：`v1.12.0-20241201` + +## 发布分支管理 + +在 `1.x` 阶段，Olares 遵循结构化的每月发布节奏： + +1. 每月月底，从 `main` 分支创建一个发布分支（例如 `release-1.11`）。 +2. 从新建的发布分支中发布第一个候选版本（例如 `v1.11.0.rc.0`）。随着测试推进，可能会发布更多候选版本。 +3. `main` 分支切换到下一个版本（例如从 `v1.11` 切换到 `v1.12`）。 +4. 正式版发布后，如果发现问题，会通过补丁版本（例如 `v1.11.1`）在对应的发布分支上解决。 + +开发者可以根据需要将 PR 提交到 `main` 分支或对应的发布分支。 + +## 升级政策与兼容性 + + Olares 正处于快速迭代阶段，新功能和变更频繁发布。为确保系统稳定性并最小化升级风险，我们采取了受控的升级策略： + +- **同次版本号内的升级**： + 同一次版本范围内升级（例如从 `1.4.0` 到 `1.4.2`）完全支持。这些更新通常包括错误修复或小的改进，不影响兼容性。 + +- **跨次版本号的升级**： + 从一个次版本升级到另一个次版本（例如从 `1.4.x` 到 `1.5.x`）通常涉及较大的更改，例如新功能或架构更新。由于这些更改可能不向下兼容，因此不支持自动升级。用户需要手动卸载现有版本后安装新版本。 + +你正在使用的版本类型也会决定可选择的升级路径： +- **正式版**：只能升级到更新的正式版，确保最大可靠性和稳定性。 +- **RC 版**：可以升级到较新的 RC 版或正式版。 +- **每日构建版**：可以升级到较新的每日构建版、RC 版或正式版。 + +::: tip 未来升级计划 +从下一个主版本起，Olares 计划全面支持相同主版本号内所有版本的无缝自动升级。 +::: \ No newline at end of file diff --git a/docs/zh/developer/install/windows-via-docker-image.md b/docs/zh/developer/install/windows-via-docker-image.md new file mode 100644 index 000000000..039fd37c7 --- /dev/null +++ b/docs/zh/developer/install/windows-via-docker-image.md @@ -0,0 +1,166 @@ +--- +outline: [2, 3] +description: 了解如何通过 WSL 2 和 Docker 在 Windows 上安装和运行 Olares，包括系统准备、环境配置以及容器管理。 +--- +# 使用 Docker 镜像在 Windows 上安装 Olares +你可以通过 Docker 可以在容器化环境中安装和运行 Olares。本文将带你了解：如何使用 Docker 和 WSL 2 设置 Olares，准备安装环境，完成激活流程，并管理容器的生命周期。 + +:::warning 不适用于生产环境 +Windows 版 Olares 目前存在以下限制： +- 不支持分布式存储 +- 无法添加本地节点 + +建议仅用于开发或测试环境。 +::: + + + +## 系统要求 +Windows 设备需满足以下条件： +- CPU：4 核及以上 +- 内存：不少于 16GB 可用内存 +- 存储空间：建议使用 SSD，且可用磁盘空间不少于 64GB +- 支持的系统： + - Windows 10 或 11 + - Linux（WSL 2 环境）：Ubuntu 20.04 LTS 及以上；Debian 11 及以上 + +## 开始之前 +开始安装前，请确保： +- 系统中已安装并运行 [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/)。 + :::info WSL 2 and Hyper-V + 如果 Docker Desktop 的模式为 **Hyper-V**，则无法启用 Olares 的 GPU 支持。请确保 Docker Desktop 在 **WSL 2** 模式下运行。 + ::: +- 已知当前设备的 IP 地址。 + ::: tip 查看 IP 地址 + 在 PowerShell 或命令提示符中，使用下列命令确认 IP 地址： + ```bash + ipconfig | findstr /i "IPv4.*192" + ``` + ::: +- 已通过 LarePass [创建 Olares ID](/zh/manual/get-started/create-olares-id.md) 且使用默认的 `olares.cn` 域名。 + +## 配置 WSL 2 +1. 打开 PowerShell，运行以下命令确认系统中安装的 WSL 内核版本： + ```powershell + wsl --version + ``` + 示例输出： + ```PowerShell{2} + WSL 版本： 2.4.8.0 + 内核版本： 5.15.167.4-1 + WSLg 版本： 1.0.65 + MSRDC 版本： 1.611.1-81528511 + DXCore 版本： 10.0.26100.1-240331-1435.ge-release + Windows 版本： 10.0.26100.3475 + ``` +2. 下载与 WSL 内核版本相匹配的文件：`https://cdn.joinolares.cn/bzImage-<内核版本号>`。 + 例如，`5.15.167.4-1` 版本对应的链接是 [https://cdn.joinolares.cn/bzImage-5.15.167.4](https://cdn.joinolares.cn/bzImage-5.15.167.4)。 + + 目前支持以下内核版本（`5.15.146.1` 及以上）： + - `linux-msft-wsl-5.15.146.1` + - `linux-msft-wsl-5.15.150.1` + - `linux-msft-wsl-5.15.153.1` + - `linux-msft-wsl-5.15.167.4` + - `linux-msft-wsl-6.6.75.1` + - `linux-msft-wsl-6.6.36.6` + - `linux-msft-wsl-6.6.36.3` +3. 设置 WSL 使用的默认版本： + ```bash + wsl --set-default-version 2 + ``` +4. 在 `C:\Users\\` 目录下创建文件 `.wslconfig`，填入以下内容： + ```txt + [wsl2] + kernel=c:\\path\\to\\your\\kernel\\bzImage- # 注意：使用双反斜杠 (\\) 作为路径分隔符 + memory=8GB # 建议设置为 16GB + swap=0GB + ``` + :::info + 如果在修改 `.wslconfig` 文件之前已经安装了 Docker Desktop，建议先删除 WSL 中已安装的 `docker-desktop` 发行版： + ```bash + wsl --unregister docker-desktop + wsl --unregister docker-desktop-data # 如果存在此版本 + ``` +5. 重启 Windows 使变更生效。 + +## 更新 Docker 的镜像源 +添加 Olares 的镜像源，提高镜像拉取速度： +1. 打开 Docker Desktop，选择 **Settings** > **Docker Engine**。 +2. 修改 Docker daemon 的 json 文件，添加镜像源： + ```json{9-11} + { + "builder": { + "gc": { + "defaultKeepStorage": "20GB", + "enabled": true + } + }, + "experimental": false, + "registry-mirrors": [ + "https://mirrors.joinolares.cn" + ] + } + ``` +3. 点击 **Apply & restart** 使变更生效。 + +## 运行 `olaresd-proxy` +1. 下载 `olaresd-proxy`：[https://cdn.joinolares.cn/olaresd-proxy-v0.1.0-windows-amd64.tar.gz](https://cdn.joinolares.cn/olaresd-proxy-v0.1.0-windows-amd64.tar.gz)。 +2. 解压文件，打开 `olaresd-proxy`。 + :::info 保持 `olaresd-proxy` 在后台运行 + 在安装和激活 Olares 的整个过程中，确保 `olaresd-proxy` 在后台运行。 + ::: + +## 使用 Docker CLI 运行 Olares +:::warning CUDA 版本要求 +如果需要启用 GPU 支持，请确保 CUDA 版本为 12.4 或以上。较低版本不支持 GPU 功能。 +::: +使用下列命令拉取 Olares 的镜像。 +将 `` 替换为设备的 IP 地址，将 `-cn` 替换为想要使用的 Olares 版本： +::: code-group +```bash{2,9} [无 GPU] +docker run -d --privileged -v oic-data:/var \ + -e HOST_IP= \ + -p 80:80 \ + -p 443:443 \ + -p 30180:30180 \ + -p 18088:18088 \ + -p 41641:41641/udp \ + --name oic \ + beclab/olares:-cn +``` +```bash{1,2,9} [支持 GPU] +docker run --gpus all -d --privileged -v oic-data:/var \ + -e HOST_IP= \ + -p 80:80 \ + -p 443:443 \ + -p 30180:30180 \ + -p 18088:18088 \ + -p 41641:41641/udp \ + --name oic \ + beclab/olares:-cn +``` +::: +其中： + - `-d`：以分离模式（detached mode）启动容器，允许其在后台运行。 + - `--privileged`：授予容器完整的系统权限。 + - `-v oic-data:/var`：将 Docker 数据卷（`oic-data`）挂载到容器内的 `/var` 目录以持久化数据。 + - `-e HOST_IP=`：设置主机设备的 IP 地址作为环境变量 + - `-p 80:80`：将主机的 `80` 端口映射到容器的 `80` 端口。 + - `-p 443:443`：将主机的 `443` 端口映射到容器的 4`43` 端口。 + - `-p 30180:30180`：将主机的 `30180` 端口映射到容器的 `30180` 端口。 + - `-p 18088:18088`：将宿主机的 `18088` 端口映射到容器的 `18088` 端口。 + - `-p 41641:41641/udp`：将宿主机的 `41641` UDP 端口映射到容器的 `41641` UDP 端口。 + - `--name oic`：将容器命名为 `oic`（Olares in container）方便后续引用。 + - `beclab/olares:-cn`：指定 Olares Docker 镜像及版本，例如`beclab/olares:1.11.5-cn`。 + +容器启动后，你会看到一个容器 ID。 + +:::warning 请勿添加 `--rm` 参数 +`--rm` 参数会在容器停止后自动删除容器。如果发生这种情况，将无法重新启动容器，必须重新安装 Olares 才能再次运行。不使用此参数可以在停止后保留容器，让你能够通过 `docker start` 命令恢复运行。 +::: + + + + + + diff --git a/docs/zh/developer/install/windows.md b/docs/zh/developer/install/windows.md new file mode 100644 index 000000000..4e30e4351 --- /dev/null +++ b/docs/zh/developer/install/windows.md @@ -0,0 +1,228 @@ +--- +outline: [2, 3] +description: 通过 WSL 在 Windows 系统安装配置 Olares 的完整步骤，包括环境要求和激活设置。 +--- +# 在 Windows 上使用脚本安装 Olares +本文介绍如何在 Windows （WSL 2）上使用脚本安装 Olares。 + +:::warning 不适用于生产环境 +Windows 版 Olares 目前存在以下限制： +- 不支持分布式存储 +- 无法添加本地节点 + +建议仅用于开发或测试环境。 +::: + + + +## 系统要求 +Windows 设备需满足以下条件： +- CPU：4 核及以上 +- 内存：不少于 16GB 可用内存 +- 存储空间：建议使用 SSD，且可用磁盘空间不少于 64GB +- 支持的系统： + - Windows 10 或 11 + - Linux（WSL 2 环境）：Ubuntu 20.04 LTS 及以上；Debian 11 及以上 +## 配置系统环境 +1. 启用虚拟化所需的 Windows 功能。 + + a. 打开**控制面板**，依次进入**程序** > **程序和功能** > **启用或关闭 Windows 功能**。 + + b. 在弹出的 **Windows 功能** 窗口中，勾选以下选项： + - **Hyper-V**（Windows 10 家庭版和 Windows 11 家庭版无此选项） + - **适用于 Linux 的 Windows 子系统** + - **虚拟机平台** + + c. 点击**确定**，然后根据提示重启电脑。 + +2. 设置当前用户的执行策略。 + + a. 以管理员身份打开 PowerShell，运行以下命令： + ```powershell + Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser + ``` + b. 当提示是否更改执行策略时，输入 `A` 并按下 **Enter** 确认。 + + ```powershell{5} + Execution Policy Change + The execution policy helps protect you from scripts that you do not trust. Changing the execution policy might expose + you to the security risks described in the about_Execution_Policies help topic at + https:/go.microsoft.com/fwlink/?LinkID-135170. Do you want to change the execution policy? + [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "N"): + ``` + +## 安装 Olares +1. 点击 https://cn.windows.olares.sh 下载安装脚本 `publicInstall.latest.ps1`。 + +2. 执行安装脚本。 + + a. 以管理员身份打开 PowerShell 并导航至脚本所在文件夹。例如，如果脚本在 `Downloads` 文件夹里，则执行以下命令： + ```powershell + cd C:\Users\\Downloads + ``` + + b. 进入正确的文件目录后，执行以下命令： + ```powershell + .\publicInstall.latest.ps1 + ``` + :::warning 需要管理员权限 + 不以管理员身份运行 PowerShell 会导致安装失败。参考[如何确认 PowerShell 是否以管理员身份运行](#如何确认-powershell-是否以管理员身份运行)。 + ::: + +3. 出现安全提示时，输入 `R` 并按下 **Enter** 以运行脚本，开始安装 Olares。 + + ```powershell{4} + Security warning + Run only scripts that you trust. While scripts from the internet can be useful, this script can potentially harm your computer. If you trust this script, use the Unblock-File cmdlet to allow the script to run without this warning message. Do you want to run + publicInstall.latest.ps1? + [D] Do not run [R] Run once [S] Suspend [?] Help (default is "D"): + ``` +4. 选择 WSL Ubuntu 的存储位置。请输入一个可用磁盘的盘符，并确保所选磁盘至少有 **80 GB** 的可用空间。 + ```powershell{8} + Installing Olares will create a WSL Ubuntu Distro and occupy at least 80 GB of disk space. + Please select the drive where you want to install it. + + Available drives and free space: + C:\ Free Disk: 391.07 GB + D:\ Free Disk: 281.32 GB + + Please enter the drive letter (e.g., C): + ``` + +5. 配置防火墙规则。输入 `yes` 自动设置防火墙规则，或者输入 `no` 跳过自动设置。
+ 如果你选择跳过，可以[暂时关闭防火墙](#如何关闭-windows-defender-防火墙)，或[手动添加 TCP 入站规则](#如何手动设置防火墙规则)。 + ```powershell{2} + Accessing Olares requires setting up firewall rules, specifically adding TCP inbound rules for ports 80, 443, and 30180. + Do you want to set up the firewall rules? (yes/no): + ``` +6. 确认 Windows 的 IP 地址。输入 **Y** 确认，或者 **R** 重新输入。 + + ```powershell + The NAT gateway (the Windows host)'s IP is 192.168.50.136. Confirm [Y] or Re-enter [R]? + ``` + ::: tip 获取 Windows IP 地址 + 你可以提前通过在 Windows 命令行里执行 `ipconfig` 获取 Windows 的 IPv4 地址。 + ::: + + + +:::info 安装遇到报错？ +如果安装过程中出现错误，请先执行以下命令卸载： +```powershell +wsl --unregister ubuntu +``` +卸载完成后，重新运行安装命令进行安装。 +::: + + + + + + + + +## 常见问题 + +### 如何确认 PowerShell 是否以管理员身份运行？ + +如果 PowerShell 窗口的标题栏显示“管理员: Windows PowerShell”，说明已以管理员权限启动。 + +![使用管理员权限打开 PowerShell](/images/manual/get-started/confirm-run-powershell-as-admin.png#bordered){width=70%} + +如果没有看到“管理员”标识，你可以尝试以下两种方式启动 PowerShell： +- 在开始菜单中搜索“PowerShell”，右键点击 Windows PowerShell，选择**以管理员身份运行**。 +- 按下 **Win** + **R**，输入“powershell”，然后按 **Ctrl** + **Shift** + **Enter** 打开管理员模式的 PowerShell。 + +### 如何配置 WSL 的 CPU 和内存？ +在 WSL 上安装 Olares 时，默认内存分配为 `12GB`。但是，你可以在安装之前调整分配的内存大小，或在安装完成后调整内存和 CPU。 + +**在安装之前调整内存** + +例如分配 16GB 内存： +1. 使用如下信息添加用户变量。 + - **变量名**: `WSL_MEMORY` + - **变量值**: `16` + + ![添加用户变量](/images/manual/get-started/add-user-variable.png#bordered) +2. 点击**确定**使变更生效。 + :::tip 提示 + 如果你已经打开了一个 PowerShell 窗口，环境变量的更改不会在当前会话中生效。请务必以管理员身份打开一个新的 PowerShell 窗口，然后再运行安装脚本。 + ::: + +**安装完成后调整内存和 CPU** + +安装完成后，系统会在用户主目录下生成一个名为 `.wslconfig` 的配置文件（路径为 `C:\Users\<你的用户名>\`）。可以通过编辑此文件调整内存和 CPU 设置。默认配置如下： +```bash +[wsl2] +memory=12GB +swap=0GB +``` +例如，设置为使用 4 核 CPU： +1. 在文件中添加 `processors` 参数： + ```bash + [wsl2] + memory=12GB + processors=4 + swap=0GB + ``` + +2. 保存对 `.wslconfig` 文件的修改。 +3. 在 PowerShell 中运行以下命令，关闭虚拟机： + ```powershell + wsl --shutdown + ``` +4. 运行以下命令重启 Olares： + ```powershell + wsl -d Ubuntu + ``` +重启后，等待几分钟，Olares 服务会重新启动并生效。 + +### 如何在重启电脑后重新启动 Olares？ +通过以下命令手动启动 Olares 服务： +```powershell +wsl -d Ubuntu +``` + +### 如何关闭 Windows Defender 防火墙？ +:::tip 提示 +建议在完成 Olares 安装后重新启用 Windows Defender 防火墙。 +::: +按照以下步骤完全关闭防火墙： +1. 打开**控制面板** > **系统和安全** > **Windows Defender 防火墙**。 +2. 在左侧导航栏中，点击**启用或关闭 Windows Defender 防火墙**。 +3. 选择**关闭 Windows Defender 防火墙**，分别对**专用网络**和**公用网络**进行设置，然后点击**确定**。 + + ![关闭 Windows Defender Firewall](/images/manual/get-started/disable-firewall.png#bordered) + +### 如何手动设置防火墙规则？ +如果在安装时选择不自动配置防火墙规则，可以通过以下步骤手动添加规则： +1. 打开**控制面板** > **系统和安全** > **Windows Defender 防火墙**。 + + ![进入 Windows Defender 防火墙](/images/manual/get-started/select-firewall.png#bordered) +2. 在左侧导航栏中，点击**高级设置**。 + + ![选择高级设置](/images/manual/get-started/select-advanced-settings.png#bordered) +3. 在左侧导航栏中，右键点击**入站规则**，然后选择**新建规则**。 + + ![添加新规则](/images/manual/get-started/add-new-rule.png#bordered) +4. 在**新建入站规则向导**中，选择**端口**，然后点击**下一步**。 + + ![选择端口规则](/images/manual/get-started/select-port.png#bordered) +5. 在**特定本地端口**输入框中，输入 `80`, `443`, `30180`，然后点击**下一步**。 + + ![指定端口](/images/manual/get-started/specify-port.png#bordered) +6. 选择**允许连接**，然后点击**下一步**。 + + ![允许连接](/images/manual/get-started/allow-the-connection.png#bordered) +7. 确保规则适用于**域**、**专用**和**公用**网络，然后点击**下一步**。 + + ![确认规则适用范围](/images/manual/get-started/confirm-rules.png#bordered) +8. 为规则提供一个名称，然后点击**完成**。 + + ![命名规则](/images/manual/get-started/name-the-rule.png#bordered) + +### 如何卸载 Olares？ +如果需要卸载 Olares，可以在 PowerShell 中运行以下命令： +```powershell +wsl --unregister ubuntu +``` \ No newline at end of file diff --git a/docs/zh/index.md b/docs/zh/index.md new file mode 100644 index 000000000..78974ac54 --- /dev/null +++ b/docs/zh/index.md @@ -0,0 +1,59 @@ +--- +# https://vitepress.dev/reference/default-theme-home-page +layout: home + +hero: + name: "Olares" + text: "开源个人云操作系统" + tagline: "让数据主权回归个人" + actions: + - theme: brand + text: 什么是 Olares？ + link: /zh/manual/docs-home + - theme: alt + text: 在 GitHub 上关注我们 + link: https://github.com/beclab/olares + +features: +- icon: 🚀 + title: Olares 快速上手 + details: 在你的硬件上快速部署 Olares，即刻开始掌控你的数据。 + link: /manual/get-started/ + +- icon: ⚙️ + title: 驾驭你的系统 + details: 深入了解 Olares 的系统应用，随心配置、个性化和访问你的个人云。 + link: /manual/olares/ + +- icon: 📱 + title: 熟悉 LarePass 客户端 + details: 通过 LarePass—Olares 的跨平台客户端，安全访问和管理 Olares。 + link: /manual/larepass/ + +- icon: 💡 + title: 探索使用场景 + details: 通过真实的教程和使用案例，探索 Olares 丰富多样的应用方式。 + link: /use-cases/ +--- + + diff --git a/docs/zh/manual/best-practices/index.md b/docs/zh/manual/best-practices/index.md new file mode 100644 index 000000000..db04766ea --- /dev/null +++ b/docs/zh/manual/best-practices/index.md @@ -0,0 +1,22 @@ +--- +description: 通过最佳实践与进阶指南，深入挖掘 Olares 的性能、安全与高级定制能力。. +--- +# 进阶篇：Olares 最佳实践与高级教程 + +本节提供深入的操作指南与经验证的最佳实践，帮助你在 Olares 上获得更高性能、更强安全性及更灵活的高级定制。无论是优化环境、保护数据，还是满足高阶工作流需求，这些资源都可作为初始部署之外的实战参考。 + +- [为 Olares 配置自定义域名](set-custom-domain.md) +- [安装多节点 Olares 集群](install-olares-multi-node.md) +- [使用 Wise 构建知识中心](organize-content.md) +- [设置 SMTP](set-up-SMTP-service.md) + + + + + + + + + + + diff --git a/docs/zh/manual/best-practices/install-olares-multi-node.md b/docs/zh/manual/best-practices/install-olares-multi-node.md new file mode 100644 index 000000000..0b9bd0c32 --- /dev/null +++ b/docs/zh/manual/best-practices/install-olares-multi-node.md @@ -0,0 +1,158 @@ +--- +outline: [2, 3] +description: Olares 多节点集群部署教程，包括主节点配置、工作节点添加和网络变更处理，助你搭建可扩展的分布式环境。 +--- + +# 安装多节点 Olares 集群 + +默认情况下，Olares 的安装会部署单节点集群。从 v1.11.3 开始，Olares 支持添加子节点。本教程将指导你如何配置主节点并添加子节点，以创建一个可扩展的多节点 Olares 集群。 + +:::warning Alpha 功能 +此功能目前处于 **Alpha** 阶段，可能存在性能问题并需要额外的手动配置，不建议用于生产环境。如果遇到任何问题，请在 [Olares 的 GitHub 仓库](https://github.com/beclab/Olares/issues)中提交 Issue。 +::: +:::info 仅支持 Linux +当前仅支持 Linux 系统节点加入 Olares 集群。 +::: + +## 目标 + +通过本教程，你将学习： + +- 在主节点上安装支持 JuiceFS 的 Olares。 +- 向集群中添加子节点。 +- 处理可能的网络变化，确保集群能够持续高效运行。 + +## 准备工作 + +在开始之前，请确保满足以下条件： + +- 熟悉 Kubernetes 和系统管理。 +- 主节点和子节点必须在同一个本地网络中。 +- 主节点和子节点必须有唯一的主机名，以避免冲突。 +- 子节点必须能够通过 SSH 连接到主节点。这意味着： + - 如果使用 root 用户或具有 `sudo` 权限的用户：需要将子节点的 SSH 公钥添加到主节点的 `authorized_keys` 文件中。 + - 如果使用非 root 用户：需要在主节点上启用基于密码的 SSH 身份验证。 + +## 第一步：设置主节点 + +::: tip 卸载已有的 Olares 集群 +如果你已经使用默认的安装命令在当前节点上安装了 Olares 集群，运行 `olares-cli uninstall --all` 命令将其卸载。 +::: + +在主节点上运行以下命令以启用 JuiceFS 支持： + +```bash +export JUICEFS=1 \ +&& curl -sSfL https://cn.olares.sh | bash - +``` + +此命令将安装 Olares，并内置一个 MinIO 实例作为后端存储。安装过程与单节点安装相同，系统会提示你输入域名并提供 Olares ID 的用户名。 + +:::tip 自定义存储 +如果你已经有自己的 MinIO 集群，或有一个 S3（或 S3 兼容）存储桶，可以将 Olares 配置为使用这些存储，而不是内置的 MinIO 实例。 +::: + +## 第二步：向集群添加子节点 + +1. 在子节点上，从 https://joincluster.joinolares.cn 下载 `joincluster.sh`。 +2. 使用必要的环境变量运行 `joincluster.sh` 脚本。这些变量用于告诉子节点如何连接到主节点。必须要设置 `MASTER_HOST` 变量，该变量指定主节点的 IP 地址： + ```bash + export MASTER_HOST=192.168.1.15 + ./joincluster.sh + ``` + +下面是可能需要设置的变量列表： + +| **变量** | **描述** | +| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `MASTER_HOST` | 主节点的 IP 地址。
必填项。 | +| `MASTER_NODE_NAME` | 主节点的 Kubernetes 节点名称。
如果未指定，脚本会交互式提示你确认所需参数。
可选项。 | +| `MASTER_SSH_USER` | 用于通过 SSH 登录主节点的用户名。
默认是 root。 | +| `MASTER_SSH_PASSWORD` | SSH 用户的密码。
如果未使用 SSH 密钥，则必填。 | +| `MASTER_SSH_PRIVATE_KEY_PATH` | 用于身份验证的私有 SSH 密钥路径。
如果未指定，脚本会交互式提示你确认所需参数。
默认路径为 `/root/.ssh/id_rsa`。 | +| `MASTER_SSH_PORT` | 主节点 SSH 服务的端口号。
默认值为 `22`。 | + +:::info + +- 非 root 用户必须提供密码以用 `sudo` 执行命令。因此，如果使用非 root 用户作为 `MASTER_SSH_USER`，且未指定 `MASTER_SSH_PASSWORD`，将无法继续。 +- 使用 `export` 设置的环境变量会在当前终端会话中保持有效。切换不同配置时，需清除（`unset`）任何冲突的变量。 + `bash + unset MASTER_SSH_PRIVATE_KEY_PATH + ` + ::: + +## 使用示例 + +以下是一些实际示例，帮助你理解在不同场景下如何使用 `joincluster.sh` 脚本。 + +### 示例 1：默认设置 + +如果主节点的 IP 是 `192.168.1.15`，使用默认用户（`root`）和端口（`22`），主节点已在 `/root/.ssh/authorized_keys` 中包含当前节点的公钥 `/root/.ssh/id_rsa.pub`，运行： + +```bash +export MASTER_HOST=192.168.1.15 +./joincluster.sh +``` + +### 示例 2：自定义 SSH 密钥路径 + +如果主节点的 IP 是 `192.168.1.15`，SSH 端口是 `22`，用户是 `root`，而子节点使用位于 `/home/olares/.ssh/id_rsa` 的自定义 SSH 密钥，运行： + +```bash +export MASTER_HOST=192.168.1.15 \ +MASTER_SSH_PRIVATE_KEY_PATH=/home/olares/.ssh/id_rsa +./joincluster.sh +``` + +### 示例 3：使用非 root 用户和密码 + +如果主节点的 IP 是 `192.168.1.15`，SSH 端口是 `22`，用户是具有 `sudo` 权限的 `olares`，并且密码是 `olares`，运行： + +```bash +export MASTER_HOST=192.168.1.15 \ +MASTER_SSH_USER=olares \ +MASTER_SSH_PASSWORD=olares +./joincluster.sh +``` + +## 卸载子节点 + +在子节点上运行以下命令： + +```bash +olares-cli olares uninstall +``` + +## 处理网络变化 + +集群设置完成后，网络配置的变化可能会中断主节点与子节点的通信。 + +### 如果主节点网络发生变化 + +- **如果主节点切换到另一个局域网**：Olares 系统守护进程（olaresd）会检测到这一变化，触发 `olares-cli` 调用 `changeip` 命令。此时主节点将继续工作，但子节点无法与主节点通信，导致无法正常运行。 + +- **如果主节点的 IP 在同一局域网内发生变化**：子节点同样会失去通信，因为它们无法自动检测新的 IP。为解决此问题，可以在子节点上使用 `olares-cli` 命令更新主节点的 IP 地址并重启相关服务： + + ```bash + sudo olares-cli olares change-ip -b /home/olares/.olares --new-master-host 192.168.1.18 + ``` + + 其中： + + - `-b /home/olares/.olares`：指定 Olares 的基础目录（默认值为 `$HOME/.olares`）。 + - `--new-master-host 192.168.1.18`：指定主节点的新 IP 地址。 + +### 如果子节点网络发生变化 + +- **如果子节点切换到另一个局域网**：子节点将失去与主节点的通信，无法正常运行。 + +- **如果子节点的 IP 在同一局域网内发生变化**：olaresd 会自动将新 IP 上报给主节点，无需手动干预。 + +## 了解更多 + +- [Olares 系统架构](../system-architecture.md#分布式存储)：了解支持 Olares 的分布式文件系统，确保可扩展性、高可用性以及无缝的数据管理。 +- [系统守护进程](../../developer/install/installation-overview.md#系统守护进程olaresd)：olaresd：了解 orchestrates 和管理 Olares 核心功能的中央系统进程。 +- [数据](../concepts/data.md#juicefs)：探索 Olares 如何利用 JuiceFS 提供统一文件系统，实现高效的数据存储和检索。 +- [Olares CLI](../../developer/install/cli/olares-cli.md)：深入了解用于管理 Olares 安装的命令行工具。 +- [Olares 环境变量](../../developer/install/environment-variables.md)：了解支持 Olares 高级配置的环境变量。 +- [安装 Olares](../get-started/install-olares.md)：了解安装与激活 Olares 的过程。 diff --git a/docs/zh/manual/best-practices/organize-content.md b/docs/zh/manual/best-practices/organize-content.md new file mode 100644 index 000000000..7b40a5551 --- /dev/null +++ b/docs/zh/manual/best-practices/organize-content.md @@ -0,0 +1,208 @@ +--- +outline: [2, 3] +description: 使用 Wise 构建知识库的完整教程，学习如何收集网页内容、管理文档、订阅 RSS 和搜索资料，打造个人信息中心。 +--- +# 使用 Wise 打造知识中枢 + +在不同来源和设备之间管理信息往往充满挑战。你可能正在使用多个工具来收藏文章、跟踪 RSS 订阅或管理文档，最终却导致工作流程碎片化。 + +Wise 是 Olares 的内置应用，旨在集中管理和组织你的知识。它不仅能从网络和设备中收集信息，还能通过本地推荐算法，帮助你以私密方式发现有价值的内容，而不受第三方推荐算法影响。 + +本教程将指导你如何利用 Wise 和 LarePass 在不同平台间收集、整理和访问内容。 + +## 目标 + +通过本教程，你将学会如何： + +- 使用 LarePass 浏览器扩展或移动客户端收集网页内容。 +- 上传 PDF 和 EPUB 等现有文件到 Wise，同一管理你的内容。 +- 订阅 RSS 订阅源，随时了解关注的博客、播客或视频播放列表的最新动态。 +- 快速定位并检索你在个人信息中枢中整理的任何内容。 + +## 开始之前 + +开始以前，请确保： + +- Olares 设备已激活并正常运行。 +- Olares ID 已[备份助记词](../larepass/back-up-mnemonics.md)。 +- 手机上已安装 LarePass 应用。 + +## 安装 LarePass 浏览器扩展 + +LarePass 浏览器扩展是内容发现和内容收集的核心应用。 + +::: tip 仅支持 Chrome +LarePass 扩展目前仅支持 Chrome 浏览器。 +::: + + + + + + +:::tip 快捷访问 +安装完成后，将 LarePass 扩展固定到 Chrome 扩展菜单中，方便后续快速访问。 +::: + +登录后，LarePass 浏览器扩展将与你的 Olares 设备同步。这意味着你通过 LarePass 扩展收集的所有内容都会自动添加到 Wise 库中。 + +## 收集在线内容 + +你可以使用 LarePass 浏览器扩展或移动客户端收集在线内容，包括网页文章、视频和播客等。 + +### 通过 LarePass 扩展收集 + +::: tip 上传 Cookie 以优化体验 +一些网站会限制匿名用户访问。这种情况下，你可以将 Cookie 上传到 Olares 以优化体验。 + +1. 登录该网站，打开 LarePass 扩展。 +2. 进入**收集**> **Cookie** 页面，并点击**上传**。鼠标悬停可查看 Cookie 详情。如果不想上传某个 Cookie 项，可以点击 **X** 按钮取消选择。 +::: + +通过 LarePass 扩展收集网页内容： + +1. 打开内容页面，如 B 站视频。 +2. 打开 LarePass 扩展。扩展会自动检测并获取当前页面的可收集内容。 +3. 在**收集** > **网页**页签下，点击内容标题旁的 add_box，将该页面添加到 Wise 库中。 + + ![收集在线内容](/images/zh/manual/tutorials/wise-collect-web-content.png#bordered) + +收集成功后，你可以在 Wise 的**库** > **文章**中找到对应内容。页面上音频、视频和图片等媒体文件也会被下载到 Olares 本地的 `/download/Wise/Article` 文件夹。 + +![查看文章](/images/zh/manual/tutorials/wise-view-article.png#bordered) + +### 通过 LarePass 移动端 + +你可以将网页链接分享到 LarePass 移动客户端来收集内容。 +:::info +具体步骤可能会因操作系统和浏览器而有所不同。以下以 Safari 为例。 +::: + +1. 在浏览器中点击 ios_share，选择 LarePass 为分享对象。你可以： + - 在分享选项中选择 LarePass 的图标，或者 + - 在**其他操作**栏中选择 **LarePass** + + ![收藏到 Wise](/images/zh/manual/tutorials/wise-add-articles-via-share.png#bordered) + + LarePass 应用会自动打开并检测待分享页面的内容，并提示是否要添加至 Wise。 +2. 点击**确认**添加。 + +::: tip 复制 URL 分享 +你也可以直接复制网页 URL 并打开 LarePass。LarePass 会自动检测剪贴板中的 URL 和可收藏的内容。 +::: + +收集完成后，可以在 Wise 的**库** > **文章**中阅读收集的文章。 + +## 上传 PDF 及电子书内容 + +你可以将本地的 PDF 或 EPUB 电子书内容上传到 Wise 进行集中管理。这样可以将阅读材料、笔记和相关内容保存在一处，方便整理、检索和随时查阅。 + +1. 打开 Wise, 点击菜单栏下方的 add_circle 按钮，选择**上传**。 +2. 进入包含你想要上传文件的目录，选择文件，并点击**确认**。 + +你可以在**库** > **PDF** 下查看上传的 PDF，在**库** > **图书**下查看 EPUB 电子书。 + +![查看 PDF](/images/zh/manual/tutorials/wise-pdf.png#bordered) + +::: tip +你可以用标签高效地分类和关联相关内容，或者通过笔记直接在内容旁记录见解和想法。详细用法请参考[组织你的阅读](../olares/wise/basics.md#组织你的阅读)。 +::: + +## 订阅 RSS 内容 +你可以在 Wise 中订阅播客、博客和喜爱的视频播放列表。系统会自动下载更新的剧集和内容，让你轻松追更，同时也无需担心原内容已被删除或无法访问。另外，对于那些往往不提供 RSS 订阅源的视频网站，Wise 也能自动下载你收藏的节目。 + +### 通过浏览器扩展订阅 + +通过 LarePass 扩展订阅 RSS 步骤如下： + +1. 在浏览器中打开要订阅的 RSS 页面，例如 “加州101”的播客：`https://www.xiaoyuzhoufm.com/podcast/5e280faf418a84a0461fbd0d`。 +2. 打开 LarePass 扩展。扩展会自动识别页面的 RSS 订阅源，并显示 **RSS** 页签。 +3. 在 **RSS** 页签下，找到正确的订阅源，点击 bookmark_add 按钮以完成订阅。 + + ![订阅播客](/images/manual/tutorials/wise-sub-podcast.png#bordered) + +### 手动添加 RSS 源 + +通过以下步骤手动添加 RSS 源至 Wise： + +1. 获取目标 RSS 订阅链接，如 HackerNews 头条订阅源 `https://hnrss.org/frontpage`。 +2. 打开 Wise，在菜单栏点击 add_circle 按钮，并选择 **RSS 源**。 +3. 输入网址后，Wise 将自动识别出可用的 RSS 订阅源。 + + ![手动添加 RSS](/images/zh/manual/tutorials/wise-add-rss.png#bordered){width=50%} +4. 点击**添加**完成订阅。 + +### 自动下载收藏视频 + +除了常规的 RSS 订阅，你可以通过 LarePass 扩展和 Wise 自动下载收藏的视频。以 B 站为例： + +1. 在浏览器里打开并登陆 B 站。 +2. 打开 LarePass 扩展，在 Cookie 页签下点击**上传**按钮以完成 Cookie 上传。Olares 需要使用视频网站的 Cookie 来访问你的收藏夹并下载视频。 + + ::: tip 打开自动同步 Cookie 功能 + Cookie 信息可能会过期。建议你在 Cookie 页面启用**自动同步**功能，以确保每次访问网站时，Cookie 会自动更新。 + ::: +3. 进入你的 B 站收藏夹管理页面，新建一个收藏夹并打开。此处，我们创建了一个`收藏到 Olares`的收藏夹。 +4. 打开 LarePass 扩展。扩展会自动获取当前页面的订阅源并显示 **RSS** 页签。 + + ![订阅 B 站收藏夹](/images/zh/manual/tutorials/wise-bilibili-rss.png#bordered) +5. 选择正确的订阅源。此处我们选择 **RSS** 页签下第二个源：“UP主非默认收藏夹”。点击 bookmark_add 完成订阅。 + +订阅完成后，任何添加到此收藏夹的视频都会被 Olares 自动下载至本地。 + +::: tip 自动下载点赞投币视频 +你也可以通过 RSS 订阅方式自动下载 B 站点赞或投币的视频： +1. 在 B 站的**个人空间** > **个人资料**里获取你的 UID，通常是一串 8 位的数字。 +2. 手动添加以下 RSS 订阅源至 Wise： + - 点赞视频：`rsshub://bilibili/user/like/你的uid/` + - 投币视频：`rsshub://bilibili/user/coin/你的uid/` +::: + +### 访问 RSS 内容 + +要访问所有通过 RSS 方式订阅的内容： +1. 在左侧菜单栏中点击**订阅** > **订阅源**。 +2. 选择一个未读的 RSS 项目，进入即可观看视频、收听播客或阅读文章。 + +::: tip 智能内容推荐 +除了常规的 RSS 订阅，Wise 还提供了完全本地运行、保护隐私的智能内容推荐系统，为你提供个性化内容推送。详情请参考[本地推荐算法](../olares/wise/recommend.md)。 +::: + +## 搜索知识库内容 + + +## 了解更多 + +- [Wise 基本操作](../olares/wise/basics.md) +- [本地推荐算法](../olares/wise/recommend.md) +- [订阅和管理订阅源](../olares/wise/subscribe.md) diff --git a/docs/zh/manual/best-practices/remote.reusables.md b/docs/zh/manual/best-practices/remote.reusables.md new file mode 100644 index 000000000..cc52a9993 --- /dev/null +++ b/docs/zh/manual/best-practices/remote.reusables.md @@ -0,0 +1,24 @@ +--- +search: false +--- + + + + + +:::info 添加配置文件 +在 iOS 或 macOS 系统中启用专用网络时，需要将 VPN 配置文件添加到系统中。按照提示完成设置即可。 +::: diff --git a/docs/zh/manual/best-practices/set-custom-domain.md b/docs/zh/manual/best-practices/set-custom-domain.md new file mode 100644 index 000000000..d6689c678 --- /dev/null +++ b/docs/zh/manual/best-practices/set-custom-domain.md @@ -0,0 +1,283 @@ +--- +outline: [2, 3] +description: 详细指导如何为 Olares 设置自定义域名，包括域名验证、组织创建、成员管理和账号激活的完整配置流程。 +--- + +# 为 Olares 设置自定义域名 + +默认情况下，当你在 LarePass 中创建账户时，系统会为你提供一个带有 `olares.cn` 域名的 Olares ID。这意味着，你可以通过类似 `desktop.{your-username}.olares.cn` 的 URL 来访问自己的 Olares 服务。虽然这种默认设置能够省去常见的网络和域名配置烦恼，但在以下情形中，你可能更希望使用自己的域名： + +- **作为组织**：为所有团队成员使用与企业邮箱类似的公司域名，例如 `employee@company.com`。 +- **作为个人**：使用自己的域名，以获得更个性化的使用体验。 + +本教程将介绍如何为 Olares 设置自定义域名。 + +## 目标 +通过本教程，你将学习： +- 在 Olares Space 中添加并验证你的自定义域名 +- 创建一个组织来管理自定义域名 +- 为组织配置成员访问方式 +- 在自定义域名下创建 Olares ID +- 使用你的 Olares ID 安装并激活 Olares + +## 理解 Olares 自定义域名机制 +在 Olares 中，自定义域名通过“组织”进行管理。无论你是个人用户还是代表公司，都需要先创建一个组织。该组织将作为自定义域名配置的载体。 + +下表列出了设置自定义域名所需的步骤，以及针对个人用户、组织管理员及组织成员的责任分工。根据你自身的角色不同，实际需要执行的操作也会有所差异。 + +| 步骤 | 个人用户 | 组织管理员 | 组织成员 | +|---------------------------------------------|:-------:|:--------:|:-------:| +| 创建 DID | ✅ | ✅ | ✅ | +| 将域名添加到 Olares Space | ✅ | ✅ | | +| 为该域名创建组织 | ✅ | ✅ | | +| 向组织添加邮箱 | ✅ | ✅ | | +| 加入组织并创建 Olares ID | ✅ | ✅ | ✅ | +| 设置 Olares | ✅ | ✅ | ✅ | + +## 开始之前 + +请确保你已具备以下条件： +- 已向域名注册商购买并注册了一个可用的域名。 + :::warning 域名备案 + 中国大陆范围内访问未备案的域名可能会被运营商拦截，典型场景包括但不限于云主机、IDC 机房、部分公司专线。因此，为确保激活成功及后续正常访问，请尽量使用已备案的域名。 + ::: +- 拥有一个 Gmail 或 G-Suite 账号。目前仅支持这两种格式的账号用于加入组织域名。 +- 已在手机上安装 LarePass 应用。
+ 你将在后续步骤中使用 LarePass 登录 Olares Space，并将自定义域名与 Olares ID 进行绑定。 + +## 第 1 步：创建 DID + +DID（Decentralized Identifier，去中心化标识符）是在获得最终的 Olares ID 前，账户所处的临时状态。只有当账户处于 DID 阶段时，才能绑定自定义域名。创建方式如下： + +1. 在 LarePass 应用中，打开账户创建页面。 + +2. 点击**创建账户**以触发 DID 创建。 + + ![创建 DID](/images/manual/tutorials/create-a-did.png) + + 此操作将为你创建一个 DID 阶段的 Olares 账户。 + + ![DID 阶段](/images/manual/tutorials/did-stage.png) + +## 第 2 步：将域名添加到 Olares Space + +在绑定域名之前，你需要先在 Olares Space 中添加并验证域名。 + +1. 在浏览器中访问 [Olares Space](https://space.olares.com/)。 +2. 在手机端的 LarePass 应用中，点击右上角的扫码按钮，并扫描登录页面的二维码以登录 Olares Space。 + + ![扫描二维码](/images/manual/tutorials/scan-qr-code.png) + +3. 在 Olares Space 中，进入**域名管理**>**域名设置**，输入你的域名并点击**确认**。 + + ![添加域名](/images/manual/tutorials/add-domain.png#bordered) + +4. 验证你域名的 TXT 记录。此步骤会验证你对该域名的所有权。 + + a. 在操作列中，点击**引导**。 + b. 按照屏幕提示，将 TXT 记录添加到你的 DNS 服务商配置中。 + + ![验证 TXT](/images/manual/tutorials/verify-txt.png#bordered) + + 完成验证后，域名状态会自动更新为**等待添加域名 NS 记录**。 + +5. 验证域名的名称服务器（Name Server，或 NS）记录。此操作将把你域名的 DNS 解析委托给 Olares 的 Cloudflare。 + + a. 在操作列中，点击**引导**。 + b. 按照屏幕提示，将 NS 记录添加到你的 DNS 服务商配置中。 + + 一旦通过验证，域名状态将更新为**等待为域名申请可验证凭证**。 + + ![域名状态更新](/images/manual/tutorials/domain-added.png#bordered) + +:::tip 注意 +TXT 验证通常在 30 分钟内完成。NS 记录验证可能需要长达 2 小时。如果整个过程超过 3 小时，请联系你的 DNS 服务商进行排查。 +::: + +完成 TXT 和 NS 记录的验证后，你的域名将成功添加至 Olares Space。 + +## 第 3 步：为域名创建组织 + +此步骤将在 Olares 中为你的域名创建一个组织，并请求该域名的可验证凭证（Verifiable Credential，或 VC）。 + +::: tip 可验证凭证 +可验证凭证是一种数字格式的证明，用于在不披露额外个人信息的情况下，验证持有者的某些属性或资格。 +::: + +1. 在 LarePass 应用中创建新组织。 + + a. 在账户创建页面，点击右上角的 display_settings，进入**高级账户创建**页面。 + + b. 前往**组织 Olares ID** >**创建新组织**。与你域名对应的组织会自动显示在列表中。 + + ![创建组织](/images/manual/tutorials/create-org.png) + + c. 点击该组织名称以申请 VC。完成后，你将看到待绑定的域名。 + + d. 点击**确定**完成在 LarePass 中的组织域名绑定。 + + ![绑定组织](/images/manual/tutorials/bind-domain-with-org.png) + +2. 在 Olares Space 中，进入**域名管理**页面。此时，域名状态应变为**等待规则配置**。 + +至此，你已成功将自定义域名与某个组织绑定，接下来可以在 Olares Space 中配置域名规则。 + +## 第 4 步：添加新成员 + +域名规则决定了如何向组织添加成员。只有组织成员才能在组织域名（即你的自定义域名）下申请 Olares ID。要配置域名规则，请执行以下步骤： + +1. 在 Olares Space 中，进入**域名管理**，然后在目标域名右侧点击**查看**。 +2. 在**域名邀请规则**下，选择**指定邮箱地址**（指定邮箱地址），并点击**保存**。 + + :::tip 邀请规则 + 目前提供两种邀请规则： + - **固定邮箱后缀**：适用于使用统一公司邮箱域名（例如 `@company.com`）的大型团队。任何符合指定后缀的邮箱地址都可以申请在组织下的 Olares ID。目前仅支持添加单个邮箱后缀。账户必须符合 G-Suite 格式。 + - **指定邮箱地址**：允许你通过指定成员的邮箱地址来添加成员。如果你没有公司邮箱域名且仅需邀请少数成员加入组织，建议使用此选项。支持 Gmail 和 G-Suite 账号。 + ::: + +3. 点击**添加新用户**并输入成员的 Gmail 地址，例如 `justtest1953@gmail.com`。 + + ![设置邀请规则](/images/manual/tutorials/set-domain-rule.png#bordered) + +4. 点击**提交**完成成员添加。如果需要添加多个用户，请重复第 3 步和第 4 步。 + +:::tip 维护成员列表 +作为组织管理员，你可以随时在**域名管理**页面管理组织成员列表。 +::: + +## 第 5 步：使用自定义域名创建 Olares ID + +要使用该域名，需要在组织下申请一个 Olares ID。 + +1. 在 LarePass 应用的账户创建页面，点击右上角的 display_settings 进入**高级账户创建**页面。 +2. 点击**组织 Olares ID** >**加入已有组织**。 +3. 输入组织域名（即已验证的自定义域名），然后点击**继续**。如果出现错误，请检查域名拼写是否正确，并确认在 Olares Space 中的域名规则已正确配置。 +4. 为成员申请 VC。 + + a. 在系统提示时，选择 Google 作为你的 VC 凭证提供商。 + b. 使用之前添加的 Gmail 帐号登录，并授权 VC 验证。 + + ![加入组织](/images/manual/tutorials/join-org.png) + + 授权成功后，就会自动创建一个使用自定义域名的 Olares ID，例如 `justtest1953@xxxx.cloud`。 + +## 第 6 步：安装并激活 Olares +最后，你只需安装并激活 Olares，即可通过自定义域名进行访问。 + +::: tip 使用添加环境变量的脚本安装 +以下示例展示了如何在安装脚本中通过环境变量预先设置域名和用户名。 + +对于 Linux 环境，你也可以不配置环境变量，直接使用单行脚本进行安装。这种情况下，你需要在安装过程中手动输入域名和 Olares ID 前缀。 + +关于支持平台的详细安装说明，请参阅[安装指南](../get-started/install-olares.md)。 +::: + + + + + + +完成上述步骤后，你即可通过自定义域名访问安装好的 Olares。 + +## 了解更多 + +- [Olares 账户](../concepts/account.md) +- [安装 Olares](../get-started/install-olares.md) +- [设置域名规则](../../space/manage-domain.md) \ No newline at end of file diff --git a/docs/zh/manual/best-practices/set-up-SMTP-service.md b/docs/zh/manual/best-practices/set-up-SMTP-service.md new file mode 100644 index 000000000..890fbbaa2 --- /dev/null +++ b/docs/zh/manual/best-practices/set-up-SMTP-service.md @@ -0,0 +1,87 @@ +--- +outline: [2,3] +description: 本文介绍如何在 Olares 平台上配置 SMTP 服务，以实现邮件通知、邮箱验证及密码找回等功能。教程涵盖获取邮箱授权码和在 Halo 与 Teable 应用中的配置步骤。 +--- +# 设置 SMTP 邮件服务 +SMTP（Simple Mail Transfer Protocol）是一种应用层协议，用于发送和传输电子邮件。在 Olares 平台上，部分应用需要依赖 SMTP 服务来完成特定功能，例如发送动态通知、验证邮箱地址、找回密码等。 + +本文将以 Halo 和 Teable 两个应用为例，介绍如何获取邮箱授权码并完成 SMTP 配置，确保通过 Olares 部署的应用可以正常使用邮箱功能。 + +:::info +未来 Olares 会提供更灵活的方式来管理 SMTP 信息，但目前仍需手动进行部分配置。如果你在配置过程中遇到问题，请联系我们。 +::: +:::tip +配置完成后，发送的邮件可能会有延迟，或被误识别为垃圾邮件。如果邮件出现在垃圾箱，请标记为“非垃圾邮件”，以便后续正常接收。 +::: +## 目标 +通过本教程，你将学习： +- 获取邮箱的 SMTP 授权码。 +- 在不同的应用中正确配置 SMTP 服务。 + +## 第一步：获取邮箱 SMTP 授权码 +SMTP 授权码由邮箱服务商（如 QQ 邮箱、Gmail、Outlook 等）提供，用于授权第三方应用通过 SMTP 协议发送邮件。 +它比直接使用邮箱密码更安全，是邮件发送的必需凭据。 + +以 QQ 邮箱为例： +1. 登录 QQ 邮箱，右上角点击**账号与安全**。 +2. 进入**安全设置**页面，找到 **POP3/IMAP/SMTP/Exchange/CardDAV/CalDAV服务**，点击**开启服务**。 + + ![开启 SMTP](/images/zh/manual/tutorials/enable-SMTP.png#bordered){width=80%} +3. 按照页面提示完成验证。验证成功后，系统会生成一组授权码。 + + ![生成授权码](/images/zh/manual/tutorials/generate-AUTH.png#bordered){width=80%} +4. 复制授权码并备注授权码用途，以便稍后配置 SMTP 服务时使用。 + +## 第二步：配置 SMTP +根据所使用的应用，SMTP 配置方式主要分为以下两种： +- [通过应用 UI 配置（以 Halo 为例）](#halo) +- [通过 Olares 控制面板配置（以 Teable 为例）](#teable) + +### 通过应用 UI 配置（以 Halo 为例）{#halo} +1. 登录 Halo，进入控制台。 +2. 选择**系统** > **设置** > **通知设置**，打开**启用邮件通知器**。 +3. 根据实际情况填入相应字段： + - **用户名**：填写你的 QQ 邮箱地址。 + - **发信地址**：留空。 + - **密码**：填写获取的 SMTP 授权码。 + - **显示名称**：自定义显示名称，该名称将包含在邮件标题中。 + - **SMTP 服务器地址**：`smtp.qq.com` + - **端口号**：`465` + - **加密方式**：`SSL` +4. 点击**测试邮箱**，验证是否能够成功发送邮件。 +5. 测试成功后，点击**保存**。 + +![Halo 配置 SMTP](/images/zh/manual/tutorials/halo-SMTP.png#bordered) +### 通过 Olares 控制面板配置（以 Teable 为例）{#teable} +Teable 应用需要通过修改环境变量来配置 SMTP 服务： +1. 打开 Olares **控制面板**，在当前用户命名空间下找到 Teable 应用。 +2. 点击**配置字典** > **teable-config**，右上角点击edit_square，打开 YAML 编辑器。 + + ![编辑 teable-config](/images/zh/manual/tutorials/teable-config.png#bordered) +3. 更新 SMTP 相关的环境变量。变量值需包含在英文字符的双引号`""`中： + ```yaml + BACKEND_MAIL_AUTH_PASS: "" # 授权码 + BACKEND_MAIL_AUTH_USER: "" # QQ 邮箱地址 + BACKEND_MAIL_HOST: "smtp.qq.com" + BACKEND_MAIL_PORT: "465" + BACKEND_MAIL_SECURE: "true" + BACKEND_MAIL_SENDER: "" # QQ 邮箱地址 + BACKEND_MAIL_SENDER_NAME: "" # 自定义一个发件名称 + ``` + 例如： + ```yaml + BACKEND_MAIL_AUTH_PASS: "abcdefghijklmnop" # 授权码 + BACKEND_MAIL_AUTH_USER: "123456789@qq.com" # QQ 邮箱地址 + BACKEND_MAIL_HOST: "smtp.qq.com" + BACKEND_MAIL_PORT: "465" + BACKEND_MAIL_SECURE: "true" + BACKEND_MAIL_SENDER: "123456789@qq.com" # QQ 邮箱地址 + BACKEND_MAIL_SENDER_NAME: "Olares's teable" # 自定义一个发件名称 + ``` +4. 在**控制面板**中点击**部署** > **teable**，在右上角点击more_vert > **restart_alt重启**。 + + ![重启 teable](/images/zh/manual/tutorials/restart-teable.png#bordered) +5. 在弹窗中输入应用名称，点击**确认**，重启 Teable。重启完成后，邮箱功能即生效。 + + ![确认重启 teable](/images/zh/manual/tutorials/confirm-restart-teable.png#bordered){width=60%} + diff --git a/docs/zh/manual/concepts/account.md b/docs/zh/manual/concepts/account.md new file mode 100644 index 000000000..79f83889e --- /dev/null +++ b/docs/zh/manual/concepts/account.md @@ -0,0 +1,71 @@ +--- +outline: [2, 3] +description: Olares 账户系统的同步机制、账户阶段和统一认证原理。包括多因素认证机制、密码系统及多设备账户同步原理。 +--- + +# 账户 + +本文介绍 Olares 账户系统的相关概念和设计。 + +## 账户同步 + +LarePass、Olares 和 Olares Space 之间的账户同步机制如下： + +- 创建 Olares 时需要提供 Olares ID，并使用该 ID 登录 LarePass 进行激活。 +- 登录 Olares Space 时，需要使用 LarePass 扫描二维码。 + +## 账户的状态 + +每个账户都有三个状态： + +### 未绑定 Olares ID（DID 阶段） +已在本地创建 DID、助记词和私钥，但尚未关联 Olares ID。 + +在这个阶段，你可以导出助记词，也可以访问 Olares Space 配置自定义域名或申请组织域名。 + +但此时无法将账户导入到其他 LarePass 客户端。 +:::tip 提示 +在 LarePass 上，当你点击**创建账户**时，就已经处于未绑定 Olares ID 状态。 +::: +### 已绑定 Olares ID +当账户绑定了 Olares ID 后，系统会在区块链上记录你的 Olares ID 与 DID 之间的关联。 + +在这个阶段，你可以通过命令行在本机上安装 Olares，或在 Olares Space 申请并激活 Olares。 + +你也可以使用导出的助记词将账户导入其他设备，实现应用间的统一认证。 + +### 已绑定 Olares +最后一个阶段是账户与 Olares 设备建立关联，此时你可以完整访问 Olares 上的所有功能，例如在 LarePass 上查看该 Olares ID 下的机器系统资源。 + +## 统一账户系统 + +Olares 支持多用户系统的统一认证。 + +1. 用户在登录页面完成登录后，后续所有请求都会自动包含认证信息。 +2. 每个用户请求都会先经过 Authelia 服务进行认证。 +3. 如果认证失败，应用会将用户重定向到登录页面重新认证。 +4. 如果认证成功，[Backend for Launcher (BFL)](https://github.com/beclab/bfl) 会附加用户的基本信息并将请求转发给应用服务。这样应用本身就不需要处理认证逻辑。 +5. 对于[共享应用（Shared application）](./application.md#共享应用)，开发者需要构建额外的 `Auth Server` 来连接应用账号与 BFL 账号。 + +## 多因素认证（MFA） + +Olares 集成了多种不同安全等级的认证因素，以确保系统中用户身份认证的安全性。 + +### 密码 + +首次激活或创建子用户时，Olares 会生成一个随机密码用于初始设置。完成身份验证后，系统会提示用户通过 LarePass 将这个初始密码更换为更强的自定义密码。 + +### 一次性密码 + +当用户执行登录等敏感操作时，Olares 要求用户输入 LarePass 生成的一次性双因素认证码。 + +## 了解更多 + +### 用户 + +- [创建 Olares ID](../get-started/create-olares-id) +- [用户角色](../olares/settings/roles-permissions.md) + +### 开发者 + +- [账户系统回调](../../developer/develop/advanced/account.md) diff --git a/docs/zh/manual/concepts/application.md b/docs/zh/manual/concepts/application.md new file mode 100644 index 000000000..e8efdfdd0 --- /dev/null +++ b/docs/zh/manual/concepts/application.md @@ -0,0 +1,128 @@ +--- +outline: [2, 3] +description: Olares 应用系统的核心概念，包括应用标识符、类型分类和权限体系。阐述系统应用、社区应用和集群范围应用的特性及依赖关系。 +--- + +# 应用 + +本文介绍 Olares 中应用标识符、类型、权限以及与应用市场集成相关的核心概念。 + +## 应用标识符 + +在 Olares 中，每个应用都有两个标识符：应用名称和应用 ID。 + +### 应用名称 + +应用名称由 Indexer 分配。Olares 团队维护的 Indexer 仓库是 [apps](https://github.com/beclab/apps)。应用在该仓库中的目录名即为其应用名称。 + +### 应用 ID + +应用 ID 是应用名 MD5 哈希值的前八个字符。例如，如果应用名称为“hello”，则其应用 ID 为“b1946ac9”。 + +应用对应的端点（Endpoint）会使用该应用 ID。 + +## 应用类型 + +Olares 包含多种类型的应用。你可以通过控制面板查看系统的各类应用，并通过命名空间来识别具体的应用类型。 + +### 系统应用 + +系统应用包括 Kubernetes、Kubesphere、Olares 组件和必要的硬件驱动。系统级命名空间包括： + +``` +os-system +kubesphere-monitoring-federated +kubesphere-controls-system +kubesphere-system +kubesphere-monitoring-system +kubekey-system +default +kube-system +kube-public +kube-node-lease +gpu-system +``` +其中，`os-system` 是 Olares 开发的组件。集群级的应用以及系统提供的各种数据库中间件都安装在这个命名空间下。 + +### 用户级系统应用 + +Olares 支持多用户，并为管理员和普通成员用户提供两个不同的系统应用命名空间： + +- **user-space-{本地名称}** + + `user-space` 命名空间用于安装用户日常交互的系统应用，包括： + - 文件管理器 + - 设置 + - 控制面板 + - 仪表盘 + - 应用市场 + - Profile + - Vault + + 这些应用之间存在相互调用，同时调用系统底层接口（如 Kubernetes 的 `api-server` 接口）。为了确保系统安全，Olares 将它们统一部署在独立的 `user-space` 命名空间中，通过沙盒机制隔离，防止恶意程序的攻击和非法访问。 + +- **user-system-{本地名称}** + + 系统应用和用户的内置应用通常不允许第三方应用直接访问。 + + 但如果数据库集群和内置应用通过[ Service Provider](../../developer/develop/advanced/provider.md) 开放了某些接口，社区应用可以通过[声明访问权限](../../developer/develop/package/manifest.md#sysdata)来使用这些服务。 + + 在这种情况下，系统会在 `user-system` 命名空间下为这些资源提供网络代理，并对来自第三方应用的网络请求进行鉴权。 + +### 社区应用 + +社区应用是由第三方开发者创建和维护的应用，涵盖从生产力工具、娱乐应用到数据分析工具等多种用途。 + +社区应用的命名空间由两部分组成：应用名称和用户的[本地名称](olares-id.md#olares-id-的组成)，例如： + +``` +n8n-alice +gitlab-client-bob +``` + +### 共享应用 + +**共享应用**是 Olares 平台中的一类特殊社区应用，旨在为 Olares 集群内的所有用户提供统一的、共享的资源或服务。 + +共享应用的特点包括： + +* **集中管理**：只有管理员账户才安装共享版应用的核心服务。管理员负责在 Olares 集群内**安装、配置和托管**应用的服务、资源以及运行环境。 +* **易于识别**：在 Olares 应用市场中，共享版应用通常带有 "Shared" 标识以便用户区分。 +* **灵活访问**：访问共享版应用的方式取决于共享应用本身的形态： + * **无界面的后端服务**: 对于通常在后端提供服务没有直接用户界面的共享应用（如 Ollama），用户通常需要通过安装一个**授权应用**作为访问入口。例如，可以通过 Open WebUI 或 LobeChat 访问 Ollama 服务。 + * **自带用户界面的完整应用**: 对于共享版应用本身就包含完整用户界面和后端服务的（例如，ComfyUI 共享版 或 Dify 共享版），管理员和集群中的其他用户都可通过直接安装该共享版应用本身获取服务的访问入口。 + +### 授权应用 + +授权应用是指具有 Olares 中特定共享应用访问权限的应用。它们通常为用户提供可交互界面，以便访问被授权共享应用的 API 或服务。 + +例如，Open WebUI、LobeChat 和 n8n 是 Ollama 的授权应用。Dify Shared 是它自身的授权应用。 + +### 依赖项 +依赖项是某些应用正常运行所必需的前置应用。安装带有依赖项的应用前，用户必须确保集群中已安装所有必需的依赖项。 + +## Service Provider + +Service Provider 机制使社区应用能够与系统应用、其他社区应用的服务进行交互。 + +![Service Provider](/images/overview/olares/image3.jpeg) + +该机制包含三个步骤： + +1. Provider 声明：开发者必须[将其应用声明为特定服务接口的 Provider](../../developer/develop/advanced/provider#申明-Provider)。 + 系统包含内置的 Provider。 + +2. 权限请求：需要使用 Service 接口的应用必须明确[申请 Provider 的权限](../../developer/develop/advanced/provider#申请-Provider-的访问权限)。 + +3. 请求处理：调用时，`user-system` 下的 `system-server` 服务作为代理，处理传入请求并执行必要的权限验证。 + +## 了解更多 + +- 用户 + + [管理应用](../olares/market.md)
+ +- 开发者 + + [在 Olares 上开发应用程序](../../developer/develop/index.md)
+ diff --git a/docs/zh/manual/concepts/architecture.md b/docs/zh/manual/concepts/architecture.md new file mode 100644 index 000000000..1f59a1a43 --- /dev/null +++ b/docs/zh/manual/concepts/architecture.md @@ -0,0 +1,24 @@ +--- +description: Olares 的 BEC 架构概述，阐述分布式节点实现数据存储和安全机制。包含 Snowinning Protocol、Olares OS 和 LarePass 三大核心组件。 +--- +# Olares 架构 + +Olares 通过区块链-边缘-客户端（BEC）架构提供了新一代去中心化互联网框架。BEC 通过在不同平台间合理分配信息，实现了数据存储的去中心化和安全性提升。 + +![BEC](/images/overview/snowinning/network-topology.jpeg) + +- **区块链层**：通过智能合约在区块链上存储高价值数据，包括去中心化身份标识（DID）和交易信息。这确保了数据的透明度、不可篡改性和可发现性。 +- **边缘层**：作为用户的去中心化网络节点，在私有边缘服务器上托管个人数据，如文档、聊天记录和照片。数据始终保持在边缘层用户的掌控之中，保障隐私和本地数据主权。 +- **客户端**：身份钱包应用，让用户可以安全地管理身份并与自托管系统进行交互，同时保持对数字凭证的所有权和隐私控制。 + +## Olares 核心组件 + +对应 BEC 架构，Olares 包含以下核心组件： + +- [**Olares ID**](olares-id.md)：一个整合了去中心化身份标识（DID）、可验证凭证（VC）和信誉数据的去中心化身份与信誉系统。通过实现去中心化环境中的透明和可验证交互来增强信任。 +- [**Olares OS**](https://github.com/beclab/Olares)：专为边缘设备设计的完整自托管操作系统。用户可以托管和管理自己的数据和应用，将个人边缘设备转变为强大的主权云系统。 +- [**LarePass**](https://olares.cn/larepass)：安全统一的界面软件，连接用户和其 Olares 系统。提供身份管理、远程访问、设备管理和数据存储等核心功能，确保与 Olares 的无缝交互。 + +## 延伸阅读 + +- [主权网络](self-sovereign-network.md) \ No newline at end of file diff --git a/docs/zh/manual/concepts/data.md b/docs/zh/manual/concepts/data.md new file mode 100644 index 000000000..3bcb70bf0 --- /dev/null +++ b/docs/zh/manual/concepts/data.md @@ -0,0 +1,112 @@ +--- +outline: [2, 3] +description: Olares 数据管理架构说明，阐述文件系统类型、应用存储路径和数据库支持体系。包括 JuiceFS、PostgreSQL、MongoDB 和 Redis 的技术特性。 +--- + +# 数据 + +数据通常存储在文件系统和数据库中，其中数据库又是建立在文件系统之上的。以下是 Olares 在这两方面的设计理念： + +**文件系统方面**： + + Olares 设计用于多节点集群环境。因此在开发应用时，需要考虑程序被调度到不同节点时对文件系统的访问问题。我们致力于对开发者屏蔽这些细节。 + +**数据库方面**： + +- 对于常用数据库，开发者只需修改配置即可完成集成。 +- 不同用户和应用可以共享物理数据库实例，以节省资源开销。 + +**共同特点**： + +- 不同用户、不同应用之间的数据相互隔离。 +- 可扩展且高可用。 +- 能在系统层面进行统一的备份和恢复。 + +## 文件系统类型 + +### JuiceFS + +Olares 采用 [JuiceFS](https://juicefs.com) 作为底层的多物理节点共享文件系统方案。这样应用可以通过最简单的 HostPath PV 方式获得跨节点的文件访问能力，使 Pod 能够在集群中自由调度。 + +针对 JuiceFS 的后端对象存储方案，我们提供了 S3 和 MinIO 两种选择。 + +默认情况下，Olares 在本地安装时使用本地文件系统（FS）。不过，如果在运行 [`olares-cli prepare`](../../developer/install/cli/prepare.md) 命令时指定了 `--with-juicefs=true` 选项，系统就会安装并使用 JuiceFS，同时会搭建一个 MinIO 实例作为后端存储。 + +### 本地磁盘 + +某些应用系统中可能会出现密集的文件系统读写操作，这些密集的文件系统读写往往是碎片化的随机读写。在现有的各种分布式存储集群方案中，对于这种密集的碎片化随机读写操作，很容易造成 I/O 或 CPU 消耗过高（通常表现为较高的 I/O Wait）。 + +Olares 提供的最佳实践是充分利用节点的本地硬盘作为文件缓冲区。虽然节点的本地硬盘容量有限，但由于基本采用 SSD 硬盘，具有较高的读写性能。应用读写文件时会先在节点本地硬盘上进行缓冲，然后批量异步写入分布式文件系统。这样可以将大部分碎片化的随机读写转化为少量的顺序读写，大幅提升系统 I/O 效率。 + +## 应用存储路径 + +对于应用来说，有三种不同的存储路径用于处理不同的使用场景。 + +### UserData + +`UserData` 存储路径用于存放变动不频繁但需要跨应用访问的文件，如文档、照片和视频等。 + +应用可以通过在 `OlaresManifest.yaml` 中申请 [UserData](../../developer/develop/package/manifest.md#userdata) 权限来获取 `Home` 目录下某个目录的访问权限。比如 PhotoPrism 可以申请 `Picture` 目录的权限，qBittorrent 和 Jellyfin 可以申请 `Downloads` 目录的权限。 + +### AppData + +`AppData` 存储路径用于存放变动不频繁但需要跨节点的数据，比如配置文件。 + +应用可以在 `OlaresManifest.yaml` 中申请 [AppData](../../developer/develop/package/manifest.md#appdata) 权限。 + +### AppCache + +`AppCache` 存储路径分配给需要直接操作磁盘且性能要求较好的应用。比如系统数据库、应用日志和缓存等。缺点是无法跨节点访问。 + +应用可以在 `OlaresManifest.yaml` 中申请 [AppCache](../../developer/develop/package/manifest.md#appcache) 权限。 + +## [PostgreSQL](../../developer/develop/advanced/database.md#rds) + +作为最受欢迎的开源关系型数据库之一，PostgreSQL 具有出色的性能和丰富的插件功能。Olares 在系统中部署了 PostgreSQL，同时集成了广受欢迎的 Citus 分布式数据库插件。通过 Olares 应用运行时组件中的 PG Operator 进行集群管理，用户可以轻松扩展 PostgreSQL 节点数量，并随整个 Olares 系统进行备份或恢复。 + +如果开发者在应用中声明的 PostgreSQL 数据库为分布式类型，那么 Olares 会在 Citus 上构建其数据库，让应用充分利用分布式 PG 数据库的能力。 + +## [MongoDB](../../developer/develop/advanced/database.md#nosql) + +MongoDB 作为 NoSQL 的代表，在物联网领域有着广泛的应用场景。通过部署 [Percona Operator for MongoDB](https://github.com/percona/percona-server-mongodb-operator)，开发者在 Olares 中就拥有了云原生版本的 MongoDB 集群。 + +与 PostgreSQL 一样，Olares 也统一管理 MongoDB 的备份和恢复。用户无需具备任何 DBA 技术能力，就能轻松实现定时备份、增量备份、定点恢复等功能。 + +## [Redis](../../developer/develop/advanced/database.md#cache) + +毫无疑问，Redis 可以说是目前最受欢迎的内存缓存软件。它拥有丰富的指令，并基于 Key-Value 数据衍生出多种数据类型。很多系统甚至将其作为 KV 数据存储使用。Olares 也在系统中部署了定制的 [Redis Cluster Operator](https://github.com/beclab/redis-cluster-operator)，提供云原生版本的 Redis 集群。 + +Olares 同样接管了 Redis 集群的备份和恢复工作，用户无需为 Redis 集群提供任何单独的运维操作。 + +此外，由于 Redis 集群本身缺乏数据隔离机制，Olares 还开发了代理层工具来实现数据的 `namespace` 机制。这种隔离机制对开发者来说是完全透明的，开发者无需在代码中对数据键做任何特殊处理，只需在应用 chart 中简单配置即可实现多应用、多用户之间的数据隔离。 + +:::tip 提示 +系统使用的是 Redis 集群版本，与单机版 Redis 有所不同，建议参考 Redis 官方文档。 +::: + +## 备份 + +备份是 Olares 的备份和恢复模块。 + +它帮助用户将整个 Olares 备份到 Olares Space，同时也支持用户自定义存储位置。 + +备份操作可以按日或按周进行。每个备份计划的第一次备份是全量备份，作为该备份计划的第一个快照。后续快照均为增量备份。 + +备份对象包括： + +- Kubernetes 配置数据，如用户信息、应用信息等 +- 数据库数据，如 Redis、MongoDB、PostgreSQL 等 +- 文件系统数据，如用户通过文件管理器上传的视频、图片、各类文档等 + +备份组件还具备数据恢复能力。可以将备份快照下载到本地服务器或 Olares Space，通过重建 Kubernetes、数据库和用户个人信息，恢复出一个完整的 Olares。 + +## 了解更多 + +- 用户 + + [文件管理](../olares/files/index.md)
+ [备份与恢复](../../space/backup-restore.md) + +- 开发者 + + [文件上传](../../developer/develop/advanced/file-upload.md)
\ No newline at end of file diff --git a/docs/zh/manual/concepts/did.md b/docs/zh/manual/concepts/did.md new file mode 100644 index 000000000..32f1fa563 --- /dev/null +++ b/docs/zh/manual/concepts/did.md @@ -0,0 +1,38 @@ +--- +description: 了解去中心化标识符（DID）的定义、结构与在 Olares ID 中的助记词派生流程。 +--- + +# 去中心化标识符（Decentralized Identifier，DID） + +**去中心化标识符（DID）** 由 [W3C](https://www.w3.org/TR/did-core/) 定义，是一种自主管理、全球唯一且无需中心化注册即可验证的标识符。DID 可指向任何主体（个人、组织、物品、数据模型或抽象实体），具体由其 **控制者（Controller）** 决定。 + +DID 的核心目标是让个人与组织掌控自身身份信息，并可在无需第三方的前提下，选择性且安全地共享这些信息。 + +## DID 结构 + +一个 DID 由三部分组成： + +| 组件 | 说明 | +| :-- | :-- | +| **DID URI 方案标识** | 指明标识符的格式 | +| **DID 方法标识** | 指定用于创建 DID 的协议 / 方法 | +| **方法专属标识（Method-Specific ID）** | 方法内部唯一标识 | + +![DID Structure](/images/manual/concepts/did.png) + +## DID 的派生 + +在 Olares ID 中，DID 通过类似区块链地址的助记词算法 **自生成**，流程如下： + +> 助记词 → 私钥 → 公钥 → DID 链上地址 + +1. **助记词（Mnemonic）** + 随机生成的 12 个英文单词，用于派生私钥。 +2. **私钥（Private Key）** + 由助记词派生，需妥善保管；用于生成公钥与链上地址。 +3. **公钥与链上地址** + 由私钥计算得出，可公开分享；链上地址用于 DID 注册。 + +:::warning 重要 +请务必妥善保管私钥与助记词，避免泄露并确保可恢复性。 +::: diff --git a/docs/zh/manual/concepts/index.md b/docs/zh/manual/concepts/index.md new file mode 100644 index 000000000..0364620ad --- /dev/null +++ b/docs/zh/manual/concepts/index.md @@ -0,0 +1,23 @@ +--- +description: Olares 系统核心概念说明文档，阐述架构设计、身份验证、应用管理、网络配置和数据安全等基础理论。适合开发者理解系统运作机制。 +--- +# 概述 + +本章节帮助你了解 Olares 系统，加深对 Olares 工作原理的理解。在以下场景中可以参考本章节： + +- 开发 Olares 应用 +- 管理系统部署 +- 排查故障问题 +- 优化系统性能 + +通过以下概念来理解 Olares： + +- [架构](architecture.md) +- [Olares ID](./olares-id.md) +- [账户](./account.md) +- [应用](./application.md) +- [网络](./network.md) +- [数据](./data.md) +- [密钥](./secrets.md) + + diff --git a/docs/zh/manual/concepts/network.md b/docs/zh/manual/concepts/network.md new file mode 100644 index 000000000..03fda552c --- /dev/null +++ b/docs/zh/manual/concepts/network.md @@ -0,0 +1,94 @@ +--- +description: Olares 网络架构设计说明，阐述应用入口类型、本地访问机制、端点配置和内部网络安全策略的基本原理。 +--- +# 网络 + +Olares 为用户提供无障碍且安全灵活的网络解决方案。本文档介绍与应用访问相关的核心概念。 + +## 入口 + +每个 Olares 应用可以配置一个或多个入口来接入外部访问。入口分为三种类型： + +- **公开入口** + + - 托管博客、社交媒体等需要外部访问的服务 + - 无需认证即可访问 + - 通过 Cloudflare 提供基础安全防护 + +- **私有入口** + + - 专门为个人、家庭或团队提供服务 + - 适用于阅读器、娱乐、生产力工具、桌面应用等 + - 需要通过[认证](account.md#多因素认证mfa)才能访问 + +## 通过 LarePass 专用网络访问私有入口 + +只需在设备上安装 LarePass，并启用[专用网络](/zh/manual/larepass/private-network.md)，即可通过专属网址（如 +`https://vault.alice123.olares.com`）安全、快速地访问您的私有应用。 + +::: tip 注意 +如不启用 LarePass 专用网络，私有入口的请求会通过你的反向代理通道到达 Olares，可能会有网络延迟并产生费用。 +::: + +## 端点 + +端点是用户与应用交互的访问地址或接入点（access point）。简单来说，就是在浏览器地址栏中输入的 URL，用于访问特定的 Olares 应用或其功能。 + +典型的 Olares 应用端点格式如下： + + https://{routeID}.{domain} + +例如：`https://vault.alice123.olares.cn`，其中： + +- `vault` 是系统应用的路由 ID +- `alice123.olares.cn` 是由 Olares ID `alice123@olares.cn` 演变而来 + +## 路由 ID + +路由 ID 是用于标识特定应用或应用入口的唯一标识符。系统会根据以下规则自动生成默认路由 ID： + +- 系统应用 + - 使用预设的易记路由 ID + - 示例：`desktop`（桌面）、`market`（应用市场） +- 社区应用 + - 使用 8 位随机字符串 + 入口索引（从 0 开始） + - 示例：对于路由 ID 为 `92d76a13` 且有两个入口的应用，第一个入口为`92d76a130`，访问 URL 为 `92d76a130.alice.olares.cn` + +::: tip 注意 + +- 应用地址包含 Olares ID +- 入口索引指的是入口在 [`OlaresManifest.yaml`](../../developer/develop/package/manifest.md) 中定义的多个入口中的位置。 + ::: + +## Olares 内部网络 + +Olares 在网关架构中采用多层代理路由设计。流量经过多个层级分发： + +`集群` -> `用户` -> `应用` -> `服务组件` + +![alt text](/images/overview/olares/image4.jpeg) + +在应用内部，Olares 实现了多层安全防护。 + +- **命名空间隔离** + + - 每个应用运行在独立命名空间中 + - 所有资源限定在命名空间内 + - 应用无法将 "`ClusterRole`" 连接到 "`ServiceAccount`" + - 禁止跨命名空间访问资源 + +- **网络策略控制** + - 每个命名空间有专属网络策略 + - 入站网络请求仅限于用户的集群应用和系统应用 + - 用户级网络隔离： + - 不同用户之间的应用相互隔离 + - 统一用户的第三方应用之间相互隔离 +- **Pod 限制** + - Pod 不能使用 `hostNetwork` 服务或 `NodePort` 服务 + - 流量访问必须通过声明的入口服务和系统提供的入口代理 + - 声明为入口的 Pod 将被强制加入 Envoy 的沙箱 Sidecar，以对入站流量进行认证和授权 + +## 了解更多 + +- [为应用设置自定义域名](../olares/settings/custom-app-domain.md#自定义域名) +- [通过专用网络访问 Olares 应用](../larepass/private-network.md) diff --git a/docs/zh/manual/concepts/olares-id.md b/docs/zh/manual/concepts/olares-id.md new file mode 100644 index 000000000..1f10e9c0e --- /dev/null +++ b/docs/zh/manual/concepts/olares-id.md @@ -0,0 +1,69 @@ +--- +description: 了解 Olares ID 的定义、结构及其用途，涵盖个人/组织/实体域名类型，并阐释与去中心化标识符 (DID) 的关系。 +--- + +# Olares ID + +本文介绍 Olares ID——Olares 生态中的身份与信任基础。 + +## 什么是 Olares ID？ + +**Olares ID** 是一种去中心化身份与信用系统，用于实现信息和价值的安全、无需信任的交换。它是你在 Olares 生态中的数字身份，使个人和组织无需依赖第三方即可自主管理身份。 + +Olares ID 具备以下特点： + +- **唯一性**：类似电子邮件地址，例如 `alice123@olares.com` +- **易读易记**：人性化命名，便于分享 +- **与 DID 绑定**：具备加密安全与可验证性 + +## 为什么需要 Olares ID？ + +Olares ID 带来无缝访问、增强安全与个性化体验： + +- **便捷访问**：系统自动为应用配置子域名与访问策略，可随时随地通过域名访问。 +- **免费 HTTPS 证书**：Olares 域名自带 TLS 证书，保障加密通信。 +- **个性化且易记**：ID 与域名简单易记，展示独特在线身份。 + +例如，若你的 Olares ID 为 `alice123@olares.com`，系统自动分配以下地址： + +- `alice123.olares.com`：个人主页 +- `desktop.alice123.olares.com`：访问 Olares 桌面 +- `files.alice123.olares.com`：访问文件管理器应用 + +## Olares ID 结构 + +格式与邮箱类似，由两部分组成： + +- **本地名（前缀）** +- **域名（后缀）** + +如 `alice123@olares.com` 中，`alice123` 为本地名，`olares.com` 为域名。本地名在域内唯一，保证整体唯一性。 + +### 域名类型 + +Olares 提供三类域名： + +| 类型 | 说明 | +|------------|--------------------------------------------| +| 个人域名 | 供个人使用，目前提供默认域名 `olares.com` | +| 组织域名 | 供企业/组织使用，管理员可在成员离职时回收 | +| 实体域名 | 供应用或其他无法归类为个人/组织的实体使用 | + +### 个人 Olares ID 创建方式 + +- **[快速创建](../larepass/create-account.md#快速创建)**：选择一个可用的本地名立即生成 ID。 +- **[高级创建](../larepass/create-account.md#高级创建)**：使用可验证凭证 (VC) 将现有可信身份（如邮箱）绑定至 Olares ID。 + - 通过 OAuth 验证 + - 将社交身份与 Olares DID 建立加密关联 + +## Olares ID 与 DID 的关系 + +**DID**（去中心化标识符）是无需中心化机构即可验证的唯一标识。但 DID 难以记忆，日常使用不便。 + +Olares ID 采用类似邮箱的可读格式，使 DID 更易用，同时保持其安全性。用户创建 Olares 账户时，系统同时生成并绑定 DID。详情见 [Account 生命周期](./account#understand-the-stage-of-account)。 + +## 深入阅读 + +- [创建 Olares ID](../larepass/create-account.md) +- [去中心化标识符 (DID)](did.md) +- [Gmail issuer 服务](/zh/developer/contribute/olares-id/verifiable-credential/olares.md#gmail-issuer-service) diff --git a/docs/zh/manual/concepts/registry.md b/docs/zh/manual/concepts/registry.md new file mode 100644 index 000000000..72361ab55 --- /dev/null +++ b/docs/zh/manual/concepts/registry.md @@ -0,0 +1,26 @@ +--- +description: 介绍在区块链上注册 DID 的机制，涵盖智能合约实现、去中心化优势与当前部署方案。 +--- + +# 区块链上的 DID Registry + +当生成 DID 后，用户需在 **DID Registry** 中注册其所有权。W3C 标准并未规定具体实现方式，**Olares ID** 采用 [智能合约](/zh/developer/contribute/olares-id/contract/contract.md#smart-contract.md) 完成注册，具有以下优势： + +- **去中心化**：无需依赖中心化机构或服务商 +- **抗审查**：结构对审查与干预具有韧性 +- **全网可发现**：其他用户可轻松检索到已注册的 DID + +发行方可将关键的 DID 元数据上传到 Registry，包括： + +- DID 本身 +- [Olares ID](olares-id.md) +- RSA 公钥 +- 其他相关信息 + +DID 元数据体积小、更新频率低，适合使用主流区块链技术进行存储与检索，系统开销低且效率高。 + +目前，Olares ID 的智能合约部署在以太坊二层网络 **[Optimistic Rollups](https://optimism.io/)** 上。 + +::: info +值得一提的是，Web5 开发团队已从 ION Registry 迁移至 **DHT（分布式哈希表）网络**。与 Layer2 区块链相比，DHT 拥有更高去中心化程度，但在高节点数量下保持效率、稳定性与数据完整性更为复杂。 +::: diff --git a/docs/zh/manual/concepts/reputation.md b/docs/zh/manual/concepts/reputation.md new file mode 100644 index 000000000..986e5e938 --- /dev/null +++ b/docs/zh/manual/concepts/reputation.md @@ -0,0 +1,42 @@ +--- +description: 介绍 Olares ID 去中心化声誉系统的设计理念与实现，包括区块链数据记录、开放算法、自定义评估与实体域名支持。 +--- + +# 去中心化声誉系统 + +**DID** 与 **VC** 可在去中心化网络中标识身份，但如何为他人建立可信评价？这就需要声誉系统。在各类在线平台中，声誉系统早已广泛存在，例如： + +- Yelp、IMDb 等在线评论平台 +- 金融评分（如 [FICO Score](https://www.fico.com/en/products/fico-score)）通过聚合声明生成可信分值 + +## 传统声誉系统的局限 + +声誉系统帮助参与者判断可信度与可靠性，但传统实现存在以下问题： + +- **中心化**：用户评分存储在平台的中心化数据库中，数据不透明 +- **难以定制**：用户无法自由选择或调整评分算法 +- **易受操纵**：实体可付费刷分或提升排名，降低评分可信度 + +## Olares ID 的去中心化方案 + +**Olares ID** 基于 **DID** 与 **VC** 构建去中心化声誉系统，实现透明、可控与可信： + +![reputation](/images/manual/concepts/reputation.jpeg) + +- **链上原始数据** + 用户评分直接通过智能合约写入区块链，确保数据真实且不可篡改。 + +- **开放算法** + 算法提供者公开发布计算方法，用户可自由选择信任的评分算法。 + +- **自定义声誉评估** + 用户可访问链上原始数据，按需生成洞见，实现个性化且公平的评分。 + +- **声誉分发** + 通过专用的Market 协议分发声誉洞见，用户可从多源获取去中心化、可靠的声誉数据。 + +## 实体域名：去中心化声誉的基石 + +在 Olares ID 中，抽象实体（电影、应用、做市商等）虽不属于个人或组织，却同样需要 DID。**实体域名** 解决了该需求，使这些抽象实体拥有去中心化身份。 + +实体域名的目标是支持协议为抽象实体构建声誉系统——从而催生 Web3 版 IMDb、Yelp、LinkedIn 等平台，真正实现自治、可信的去中心化声誉网络。 diff --git a/docs/zh/manual/concepts/secrets.md b/docs/zh/manual/concepts/secrets.md new file mode 100644 index 000000000..dd23fde6e --- /dev/null +++ b/docs/zh/manual/concepts/secrets.md @@ -0,0 +1,26 @@ +--- +description: Olares 密钥管理体系说明，包括 Vault 项目、凭据、密钥和集成凭据的分类与安全机制，以及讲解敏感数据的存储策略。 +--- +# 密钥 + +Olares 根据使用场景对密钥进行分类并采用不同的管理方式。 + +| | 数据类型 | 存储位置 | 泄露风险 | 使用方式 | +|----------|-------------------------------------|------------------------------------|-----------------------------------------------------|--------------------------------------------------| +| Vault 项目 | 包括网站密码、数
据库密码、区块链
私钥等 | Vault | Olares 中的加密数据确保第三方即使登录也无法查看 | 每次使用都需要 LarePass 签名 | +| 凭证 | 安全认证后获取
的系统访问凭据：
令牌、Cookie 等 | [Infisical](https://infisical.com/) | 第三方在 Olares 中通过特定步骤认证后可查看 | 应用程序获得 Provider 权限后可通过 API 使用 | +| 密钥 | Pod 容器中使用的
敏感数据，如数据
库连接和管理账号 | ETCD | 可在[控制面板](../olares/controlhub/navigate-control-hub.md#保密字典)直接查看 | 用于 Helm 部署模板，通过 `valueFrom -> secretKeyRef` 注入环境变量 | + +## 集成凭据 + +用户可以通过在设置中登录第三方服务账号，让 Olares 中的应用访问外部服务凭据。例如： + +- 登录 Olares Space 后，备份服务可以请求令牌用于自动后台备份 +- 登录 Google 后，文件功能可以与 Google Drive 中的数据同步 + +Olares 中的应用程序可以通过[Service Provider](../../developer/develop/advanced/provider.md) 获取这些第三方服务凭据。 + +## 应用凭据 + +- Olares 中的应用可以通过系统提供的接口管理和使用[密钥](../../developer/develop/advanced/secret.md) +- 应用生成的凭据仅限该应用程序使用 \ No newline at end of file diff --git a/docs/zh/manual/concepts/self-sovereign-network.md b/docs/zh/manual/concepts/self-sovereign-network.md new file mode 100644 index 000000000..6dd367dea --- /dev/null +++ b/docs/zh/manual/concepts/self-sovereign-network.md @@ -0,0 +1,51 @@ +--- +description: 介绍 Olares 基于 DID 与区块链的自主主权网络及 BEC 架构，实现去信任的信息与价值交换。 +--- + +# 自主主权网络（Self-Sovereign Network） + +借助 [**DID**](did.md) 与 [**区块链注册表**](registry.md)，Olares 构建了基于 **Blockchain-Edge-Client（BEC）** 架构的点对点自主主权网络，消除了对第三方信任的依赖，使任意两方均可直接进行信息与价值的去信任交换。 + +## BEC 架构 + +BEC 通过在最合适的位置分布存储数据，实现彻底去中心化，由三大支柱组成： + +- **Edge（边缘）** + 用户将个人数据（文档、聊天记录、照片等）存储在私有边缘服务器上。用户与他人或服务的所有交互都通过该服务器完成。 + > Olares：开源自托管操作系统，运行在本地边缘设备，即此组件的具体实现。 + +- **Blockchain（区块链）** + 高价值数据（如 DID 和交易）存储在链上，确保透明、安全与可发现性。 + > Olares ID 通过智能合约将 DID Registry 部署于 EVM 兼容链（如 Optimism）。 + +- **Client（客户端）** + 身份钱包应用，私钥保存在移动设备，用户完全掌控。 + > LarePass：Olares 的全功能客户端，即此组件的具体实现。 + +## 通过 BEC 进行去信任信息交换 + +以下示例展示 Alice 向 Bob 发送消息的流程。二者已在区块链上注册 DID。 + +![BEC 拓扑](/images/manual/concepts/network-topology.jpeg) + +1. **终端 → Edge**：Alice 在终端设备发送消息至其 Edge 服务器。 +2. **链上定位**：Alice 的 Edge 通过区块链这一去中心化 **DNS** 定位 Bob 的 Edge。 +3. **Edge → Edge**：消息从 Alice 的 Edge 转发至 Bob 的 Edge。 +4. **签名验证**：Bob 的 Edge 以区块链为 **CA**，验证 Alice 的加密签名。 +5. **Edge → 终端**：验证通过后，消息安全地转发至 Bob 的终端设备。 + +## 通过 Otmoic 协议进行去信任价值交换 + +**Otmoic** 是建立在 **Olares ID** 之上的去信任自动价值交换协议，目标是在 **公用品** 场景中提供公平价格与透明交易。 + +![Otmoic RFQ 流程](/images/manual/concepts/rfq.jpeg) + +核心特性： + +| 功能 | 说明 | +|--------------------------|------------------------------------------------------------------------------------------| +| 链上声誉机制 | 对交易者与流动性提供者建立声誉体系，解决 **Free-Mint** 问题 | +| VC-驱动的 KYC | 通过可验证凭证完成身份验证而不损害去中心化 | +| 基于 RFQ 的价格发现 | 高效的 **Request-for-Quote** 模式进行价格撮合 | +| 原子交换（Atomic Swap） | 支持链上无信任原子交换交易 | +| 自动做市 | 流动性提供者可在 **Olares** 上安装应用参与自动做市 | diff --git a/docs/zh/manual/concepts/vc.md b/docs/zh/manual/concepts/vc.md new file mode 100644 index 000000000..73f415b81 --- /dev/null +++ b/docs/zh/manual/concepts/vc.md @@ -0,0 +1,41 @@ +--- +description: 介绍可验证凭证（VC）的定义、相关角色与六步验证流程，以及 VC 与 DID 的协同工作方式。 +--- + +# 可验证凭证（Verifiable Credential） + +在实体（无论是现实还是数字世界中的有形或无形对象）通过 **DID** 标识自身后，可以针对该实体的多项 “声明” 提供佐证文件。用于证明这些声明的文件即 **可验证凭证（VC）**。VC 是 W3C 已正式推荐的标准，与 DID 协同，能够在无需第三方信任的情况下实现安全交互。 + +举例而言： +> Alice 拥有一项“学历”声明；她的毕业证书即为验证该声明的凭证。该证书由其就读的大学签发，可通过密码学方式安全验证。当 Alice 求职时，用人单位可在面试中验证此凭证。 + +## VC 相关角色 + +以下示例展示了如何将一份毕业证书从普通凭证转化为 VC： + +![Verifiable Credential Process](/images/manual/concepts/vc-diploma.jpeg) + +1. **Issuer（签发者）** + > 对主体（Subject）做出声明并签发 VC 的实体。 + 示例中，Issuer 是 Alice 就读的大学。 + +2. **Holder（持有者）** + > 持有一个或多个 VC，并向 Verifier 提交证明（Proof）的实体。 + 此处，Holder 是 Alice。她通过钱包应用（此例为 TermiPass）存储与管理 VC。 + +3. **Verifier（验证者）** + > 通过 Presentation Definition 指定所需证明，并验证提交材料的实体。 + 示例中，Verifier 是面试 Alice 的公司。 + +## 六步验证流程 + +1. **Issuer 注册 DID**：Issuer 将其信息注册到 DID Registry。 +2. **Holder 发起请求**：Holder 向 Issuer 发送凭证签发请求。 +3. **Issuer 签发 VC**：Issuer 向 Holder 颁发含“学历”声明的 VC。 +4. **Holder 存储 VC**：Holder 将 VC 安全存储于 TermiPass。 +5. **提交 VP**：Holder 生成包含 VC 的 **Verifiable Presentation (VP)** 并发送给 Verifier。 +6. **Verifier 验签**：Verifier 通过 DID Registry 校验 VC 与 VP 的签名，确认声明有效。 + +::: tip 提示 +VC 本身并不存储在区块链上。 +::: diff --git a/docs/zh/manual/concepts/wallet.md b/docs/zh/manual/concepts/wallet.md new file mode 100644 index 000000000..747b783ad --- /dev/null +++ b/docs/zh/manual/concepts/wallet.md @@ -0,0 +1,39 @@ +--- +description: 了解数字身份钱包 LarePass 的核心功能，包括 Olares ID（去中心化身份证明）与 VC 的管理及与 Olares 的无缝交互。 +--- + +# 身份钱包应用（Identity Wallet App） + +**数字身份钱包** 是自主主权身份 (SSI) 生态的重要工具，可让用户无需中心化机构即可管理去中心化标识符（DID）、凭证 (VC) 以及与数字服务的交互。 + +**LarePass** 是 Olares 的官方身份钱包应用，为基于 Olares ID 的自托管去中心化操作系统提供安全、便捷的身份管理与访问能力。 + +## 管理 Olares ID + +创建 Olares 账户时，系统会先生成 DID 并绑定至新的 Olares ID。LarePass 提供以下功能来简化 Olares ID 的管理： + +![Olares ID management](/images/manual/concepts/create-terminus-name.png) + +- **Olares ID 创建** + - 快速创建（无需 VC 绑定） + - 高级创建（绑定 VC，现支持 Gmail Issuer Service） +- **备份 / 导入 Olares ID** + 使用助记词快速备份与恢复账户 +- **多身份管理** + 同时管理多个 DID / Olares ID + +详细说明参见 [使用 LarePass 管理账户](https://docs.olares.com/how-to/LarePass/account/)。 + +## 管理可验证凭证（VC） + +LarePass 支持绑定至 Olares ID 的 VC 全流程操作，包括签名、验证、发现与呈现： + +![VC management](/images/manual/concepts/vc-management.png) + +- **签发与存储**：安全保存来自 Issuer 的 VC +- **验证与呈现**：按需向 Verifier 提交 Verifiable Presentation +- **发现与检索**：便捷查看各身份对应的 VC 列表 + +::: tip 说明 +以上为 LarePass 与身份钱包相关的核心功能。更多使用方法请参阅 [LarePass 文档](https://docs.olares.com/how-to/LarePass/overview.html)。 +::: diff --git a/docs/zh/manual/docs-home.md b/docs/zh/manual/docs-home.md new file mode 100644 index 000000000..409840ad1 --- /dev/null +++ b/docs/zh/manual/docs-home.md @@ -0,0 +1,81 @@ +--- +description: Olares 是为本地 AI 打造的开源私有云操作系统，支持自托管服务、AI 应用部署、文件管理和安全协作，让你完全掌控数据。 +--- +# Olares 文档 Dev + +::: warning Dev 版本说明 +本文档为你提供 Olares 即将发布的版本中的功能。由于这不是一个稳定版本，其中描述的部分功能和用户界面可能尚不稳定或不完整，并且未来可能会有变动。 +::: + +## Olares 是什么？ +Olares 是一款开源个人云操作系统，旨在让你能够轻松在本地拥有并管理自己的数字资产。你无需再依赖公有云服务，而可以在 Olares 上本地部署强大的开源平替服务或应用，例如可以使用 Ollama 托管大语言模型，使用 SD WebUI 用于图像生成，以及使用 Mastodon 构建不受审查的社交空间。Olares 让你坐拥云计算的强大威力，又能完全将其置于自己掌控之下。 + +有了 Olares，自托管不再是复杂艰难的任务。它简化了诸如网络设置、域名管理和服务编排等繁琐流程，无论是初学者还是资深用户，都可以专注于真正重要的事情。 + +隐私和自主性是 Olares 的核心理念。对于希望避免依赖中心化平台的个人或团队来说，Olares 是理想之选。你的数据始终保存在自己的设备上，所有任务均在本地处理，确保应用数据和敏感信息始终掌握在手中。Olares 在保持性能和易用性的同时，赋予你对数据和应用设备完全的掌控权。 + +
+ +
+

初次使用 Olares？

+

查看入门指南，了解如何在本地设备上设置 Olares。

+
+
→
+ +
+ +## 功能亮点 + +Olares 提供了丰富的功能，旨在提升安全性、易用性和开发灵活性： + +- **企业级安全**：通过 Tailscale、Headscale、Cloudflare Tunnel 和 FRP 等工具，简化网络配置，确保私有云的安全。 +- **安全且开放的应用生态**：在安全的沙箱环境中使用近百款免费应用。[查看 Olares 应用市场](https://market.olares.com/)。 +- **统一文件系统和数据库**：支持自动扩容、备份和高可用。 +- **统一身份认证**：一次登录，访问所有 Olares 应用。 +- **AI 能力**：管理 GPU 资源，本地部署 AI 模型，构建私有知识库。 +- **内置应用**：预装多款实用应用，包括文件管理器、Vault、Wise、Profile 和仪表盘，开箱即用。 +- **随时随地访问**：通过移动端、桌面端和浏览器端专用客户端，随时随地访问设备资源。 +- **开发工具**：配套完整开发工具，轻松构建和迁移应用。 + +## 使用场景 + +以下是 Olares 的典型应用场景。 + +- **本地 AI**：在你的设备上直接托管和运行最新的开源 AI 模型，包括大型语言模型、图像生成和语音识别。构建可以与你的数据和应用程序集成的自定义 AI 助手，同时保持所有内容的私密性和安全性。 + +- **个人数据仓库**：所有个人文件，包括照片、文档和重要资料，都可以在这个安全的统一平台上存储和同步，随时随地都能方便地访问。 + +- **自托管工作空间**：利用开源 SaaS 平替方案，使用开源替代方案即可为家庭或工作团队搭建一个功能强大的协同空间。 + +- **私人媒体服务器**：用自己的视频和音乐库搭建私人流媒体服务，随时享受个性化的娱乐体验。 + +- **智能家居中心**：将所有智能设备和自动化系统集中在一个易于管理的控制中心，实现家庭智能化的简便操作。 + +- **去中心化社交媒体**：在 Olares 上部署去中心化社交媒体应用，如 Mastodon、Ghost 和 WordPress，自由建立和扩展个人品牌，无需担忧封号或支付额外费用。 + +- **学习探索**：深入学习自托管服务、容器技术和云计算，并上手实践。 + +## 选择适合的路径 + +在深入了解 Olares 之前，不妨先快速浏览一番。以下是几条路径，帮助快速了解 Olares 的功能。 + +
+ +

探索使用场景

+

发现实际应用场景，看看 Olares 如何解决常见挑战。

+ + +

阅读操作指南

+

全面了解 Olares 的各个应用。

+ + +

了解 Olares

+

掌握 Olares 的基本原理和架构。

+ +
+ +## 其他资源 + +- [开发 Olares 应用](../developer/develop/) +- [加入 Discord 社区](https://discord.com/invite/BzfqrgQPDK) +- [查看 Olares 博客](https://blog.olares.com/) \ No newline at end of file diff --git a/docs/zh/manual/feature-overview.md b/docs/zh/manual/feature-overview.md new file mode 100644 index 000000000..49137b149 --- /dev/null +++ b/docs/zh/manual/feature-overview.md @@ -0,0 +1,30 @@ +# 功能对比 +:::tip 图例说明 +- 🚀: **自动**，系统自动完成任务 +- ✅: **支持**，非开发者也能通过产品界面提示完成设置 +- 🛠️: **手动配置**，工程背景用户也需要参考教程完成设置 +- ✖️: **不支持**，不具备该功能 + ::: + +| | Olares | 群晖 | TrueNAS | CasaOS | Unraid | +|-----------|-----------------------------------------------------------------------------------------------|--------------------------|--------------------|----------------|---------------------| +| 多节点 | ✅ | ✖️ | ✅ | ✖️ | ✖️ | +| 内置应用 | ✅ (丰富的桌面应用) | ✅ (丰富的桌面应用) | ✖️ (命令行) | ✅ (简单的桌面应用) | ✅ (控制面板) | +| 免费域名 | ✅ | ✅ | ✖️ | ✖️ | ✖️ | +| SSL 证书自动化 | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | +| 反向代理 | 🚀 | ✅ | 🛠️ | 🛠️ | 🛠️ | +| VPN 管理 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| 应用入口分级 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| 多用户管理 | ✅ 用户管理
🚀 资源隔离 | ✅ 用户管理
🛠️ 资源隔离 | ✅ 用户管理
🛠️ 资源隔离 | ✖️ | ✅ 用户管理
🛠️ 资源隔离 | +| 应用统一登录 | 🚀 | ✖️ | ✖️ | ✖️ | ✖️ | +| 跨节点存储 | 🚀 (Juicefs+
MinIO) | ✖️ | ✖️ | ✖️ | ✖️ | +| 数据库方案 | 🚀 (内置云原生方案) | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| 容灾 | 🚀 (MinIO [**纠删码**](https://min.io/docs/minio/linux/operations/concepts/erasure-coding.html)) | ✅ RAID | ✅ RAID | ✅ RAID | ✅ Unraid 存储 | +| 备份 | ✅ 应用数据
✅ 用户数据 | ✅ 用户数据 | ✅ 用户数据 | ✅ 用户数据 | ✅ 用户数据 | +| 应用沙箱 | ✅ | ✖️ | ✖️ (K8S 命名空间) | ✖️ | ✖️ | +| 应用生态 | ✅ (官方 + 第三方) | ✅ (主要是官方应用) | ✅ (官方 + 第三方提交) | ✅ 主要是官方应用 | ✅ (社区应用市场) | +| 开发友好度 | ✅ IDE
✅ CLI
✅ SDK
✅ 文档 | ✅ CLI
✅ SDK
✅ 文档 | ✅ CLI
✅ 文档 | ✅ CLI
✅ 文档 | ✅ 文档 | +| 本地大模型部署 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| 本地大模型应用开发 | 🚀 | 🛠️ | 🛠️ | 🛠️ | 🛠️ | +| 客户端平台 | ✅ 安卓
✅ iOS
✅ Windows
✅ Mac
✅ Chrome 插件 | ✅ 安卓
✅ iOS | ✖️ | ✖️ | ✖️ | +| 客户端功能 | ✅ (一体化客户端) | ✅ (14个独立客户端) | ✖️ | ✖️ | ✖️ | \ No newline at end of file diff --git a/docs/zh/manual/get-started/activate-olares.md b/docs/zh/manual/get-started/activate-olares.md new file mode 100644 index 000000000..6b7359675 --- /dev/null +++ b/docs/zh/manual/get-started/activate-olares.md @@ -0,0 +1,37 @@ +--- +search: false +--- +## 激活 Olares + +使用向导 URL 和初始一次性密码进行激活和 Olares 初始化配置。 + +1. 在浏览器中输入向导 URL。进入欢迎页面后，按任意键继续。 + + ![打开向导](/images/manual/get-started/open-wizard.png#bordered) +2. 输入一次性密码，点击**继续**。 + + ![输入密码](/images/manual/get-started/wizard-enter-password.png#bordered) +3. 选择系统语言。 + + ![选择语言](/images/manual/get-started/select-language.png#bordered) +4. 使用 LarePass 应用激活 Olares。 + + a. 打开 LarePass 应用，点击**扫描二维码**，扫描向导页面上的二维码完成激活。 + :::warning 检查网络连接 + 为避免激活失败，请确保你的手机和 Olares 设备连接到同一网络。 + ::: + + ![激活 Olares](/images/manual/get-started/activate-olares.png#bordered) + + b. 按照 LarePass 上的提示重置 Olares 的登录密码。 + + ::: tip 使用相同的 ID 重新激活 Olares + + 如果你重新安装了 Olares，原有实例将不可用。要使用同一个 ID 重新激活 Olares： + 1. 在手机上打开 LarePass，你将看到红色提示：“未发现运行中的的 Olares”。 + 2. 点击**了解更多** > **重新激活**，进入二维码扫描页面。 + 3. 点击**扫描二维码**，扫描向导页面上的二维码以完成激活。 + ::: + + +设置成功后，LarePass 应用会自动返回主界面，向导页面则会跳转到登录界面。 \ No newline at end of file diff --git a/docs/zh/manual/get-started/create-olares-id.md b/docs/zh/manual/get-started/create-olares-id.md new file mode 100644 index 000000000..50c28e156 --- /dev/null +++ b/docs/zh/manual/get-started/create-olares-id.md @@ -0,0 +1,50 @@ +--- +description: 使用 LarePass 移动端应用创建 Olares ID。 +--- +# 创建 Olares ID + +Olares ID 是 Olares 生态系统中的唯一标识符，作为你的数字身份，可用于访问各种服务和功能。 + +Olares ID 由本地名称和域名两部分组成。以 `alice123@olares.cn` 为例： +- `alice123`：本地名称 +- `olares.cn`：域名 + +:::tip +要了解为什么需要 Olares ID，请参阅 [Olares ID](../concepts/olares-id.md)。 +::: + +## 下载并安装 LarePass 应用 + +在手机应用商店中搜索“LarePass”并下载。 + +## 创建 Olares ID + +::: tip +本节主要介绍如何创建个人 Olares ID。如需创建用于组织用途的 Olares ID，请参阅[创建组织 Olares ID](../../space/host-domain.md#创建组织-olares-id)。 +::: + +:::warning `.com`域名 与 `.cn`域名 +为了保证良好的激活和使用体验，Olares 为中国大陆境内用户设置了专属反向代理节点和对应的 `.cn` 的域名。首次创建 Olares ID 时，LarePass 会根据手机系统语言，默认分配 Olares ID 的域名。如果你的手机语言为英文，则会创建 `.com` 域名的 Olares ID, 可能会遇到 DNS 解析问题，进而影响后续的激活和使用。此时，需要你从 LarePass 的账号创建页面右上角进入高级账号创建模式，切换域名默认值为 `.cn`后再返回创建。 +::: + +1. 打开 LarePass 应用，点击**创建账号**。 +2. 输入想要使用的 Olares ID。需要满足以下要求： + * 之前从未被注册过 + * 长度不少于 8 个字符 + * 仅可使用小写字母和数字 +3. 点击**继续**完成创建。 + +![快速创建](/images/manual/get-started/create-olares-id.png) + +## 后续步骤 + +请妥善保管新创建的 Olares ID 和 LarePass 应用，后续步骤中会用到。 + +如果要以管理员身份安装和激活 Olares： +- [安装 Olares](./install-olares) + +如果你的团队已经部署了 Olares，需要以成员身份加入： +- [激活 Olares](./activate-olares) + +如果要登录 Olares Space 或创建基于云的 Olares： +- [管理 Olares Space 账号](../../space/manage-accounts) \ No newline at end of file diff --git a/docs/zh/manual/get-started/index.md b/docs/zh/manual/get-started/index.md new file mode 100644 index 000000000..26781f17d --- /dev/null +++ b/docs/zh/manual/get-started/index.md @@ -0,0 +1,39 @@ +--- +description: Olares 的上手指南，选择适合个人或团队的使用路径。 +--- +# 快速上手 +嗨！欢迎来到 Olares 的世界！让我们帮你在你喜欢的平台上轻松上手 Olares。 + +::: tip +想直接体验云端版本？不用自己搭建？来看看 [Olares Space 的介绍](../../space/)吧！ +::: + +
+ +
+

刚认识 Olares？

+

从创建 Olares ID 开始，轻松搞定初始设置。

+
+
→
+ +
+ +
+ +
+

已是 Olares 用户？

+

查看完整指南，玩转 Olares 的每一个功能。

+
+
→
+ +
+ +
+ +
+

想用 Olares 开启高效工作？

+

探索用例和教程，了解 Olares 如何简化你的工作流程并开启新的可能性。

+
+
→
+ +
\ No newline at end of file diff --git a/docs/zh/manual/get-started/install-and-activate-olares.md b/docs/zh/manual/get-started/install-and-activate-olares.md new file mode 100644 index 000000000..5cce8d3f2 --- /dev/null +++ b/docs/zh/manual/get-started/install-and-activate-olares.md @@ -0,0 +1,20 @@ +--- +search: false +--- +## 安装并激活 Olares +:::warning 检查网络连接 +为避免激活失败，请确保你的手机和 Olares 设备连接到同一网络。 +::: + +1. 打开 LarePass，在账号激活页面点击**发现附近的 Olares**。LarePass 将列出同一网络中检测到的 Olares 实例。 +2. 选择标记为 **Container** 的 Olares 设备，点击**立即安装**。 +3. 安装完成后，点击**立即激活**。Olares 将开始激活流程，包括初始配置和网络设置。 +4. 按照屏幕提示重置 Olares 的登录密码，然后点击**完成**。 + +![使用 LarePass 激活 Olares](/images/zh/manual/get-started/activate-olares-mdns.png#bordered) + +激活完成后，LarePass 将显示 Olares 设备的桌面地址，如 `https://desktop.marvin123.olares.cn`。 + +![从浏览器访问 Olares](/images/zh/manual/get-started/access-olares-via-browser.png#bordered){width=30%} + + \ No newline at end of file diff --git a/docs/zh/manual/get-started/install-olares-linux.md b/docs/zh/manual/get-started/install-olares-linux.md new file mode 100644 index 000000000..84408b372 --- /dev/null +++ b/docs/zh/manual/get-started/install-olares-linux.md @@ -0,0 +1,32 @@ +--- +description: 在 Linux 系统 Ubuntu 和 Debian 上安装配置 Olares 的完整步骤，包括系统要求、安装命令和激活流程。 +--- +# 在 Linux 上使用脚本安装 Olares +本文介绍如何在 Linux 上使用脚本安装 Olares。 + +## 系统要求 + +请确保设备满足以下配置要求： + +- CPU：4 核及以上 +- 内存：不少于 8GB 可用内存 +- 存储：建议使用 SSD，且可用磁盘空间不少于 64GB +- 支持的系统版本： + - Ubuntu 24.04 LTS 及以上 + - Debian 11 及以上 + +:::info 版本兼容性 +虽然以上版本已经过验证，但其他版本也可能正常运行 Olares。根据你的环境可能需要进行调整。如果你在这些平台上安装时遇到任何问题，欢迎在 [GitHub](https://github.com/beclab/Olares/issues/new) 上提问。 +::: + +## 安装 Olares + +在 Linux 命令行中，执行以下命令： + + + + + + + + \ No newline at end of file diff --git a/docs/zh/manual/get-started/install-olares.md b/docs/zh/manual/get-started/install-olares.md new file mode 100644 index 000000000..0b5807f3c --- /dev/null +++ b/docs/zh/manual/get-started/install-olares.md @@ -0,0 +1,42 @@ +--- +description: 在 Linux 系统上通过一键脚本，快速上手 Olares。 +--- +# 安装 Olares + +本文介绍如何在 Linux 系统上安装 Olares。我们推荐在 **Linux 系统**（如 Ubuntu 或 Debian）上部署 Olares，以在生产环境中获得最佳的性能与稳定性。 + +开始安装前，请先[创建 Olares ID](create-olares-id.md)，并确认操作系统与硬件已满足最低要求。 + +:::info 安装遇到问题？ +如果安装过程中遇到问题，[可以提交 GitHub Issue](https://github.com/beclab/Olares/issues/new)。提交时请提供以下信息： +- 使用的平台或环境（如 Ubuntu、Docker、WSL 等）。 +- 安装方式（脚本安装或 Docker 镜像）。 +- 详细的错误信息（包括日志、错误提示或截图）。 +::: + +## 系统要求 + +请确保设备满足以下配置要求： + +- CPU：4 核及以上 +- 内存：不少于 8GB 可用内存 +- 存储：建议使用 SSD，且可用磁盘空间不少于 64GB +- 支持的系统版本： + - Ubuntu 20.04 LTS 及以上 + - Debian 11 及以上 + +:::info 版本兼容性 +虽然以上版本已经过验证，但其他版本也可能正常运行 Olares。根据你的环境可能需要进行调整。如果你在这些平台上安装时遇到任何问题，欢迎在 [GitHub](https://github.com/beclab/Olares/issues/new) 上提问。 +::: + +## 安装 Olares + +在 Linux 命令行中，执行以下命令： + + + + + + + + diff --git a/docs/zh/manual/get-started/log-in-to-olares.md b/docs/zh/manual/get-started/log-in-to-olares.md new file mode 100644 index 000000000..8dd963747 --- /dev/null +++ b/docs/zh/manual/get-started/log-in-to-olares.md @@ -0,0 +1,17 @@ +--- +search: false +--- +## 登录 Olares + +1. 在登录页面输入 Olares 登录密码。 + + ![登录](/images/manual/get-started/log-in.png#bordered) +2. 系统会要求完成双重验证。你可以选择在 LarePass 上确认登录，或手动输入 6 位验证码。 + ::: info + 验证码有时效限制，请在过期前完成输入。如果验证码过期，需要重新生成。 + ::: + + ![确认登录](/images/manual/get-started/confirm-login.png#bordered) + +登录后你就会看到 Olares 桌面。🎉 + diff --git a/docs/zh/manual/get-started/next-steps.md b/docs/zh/manual/get-started/next-steps.md new file mode 100644 index 000000000..fa0d744ba --- /dev/null +++ b/docs/zh/manual/get-started/next-steps.md @@ -0,0 +1,122 @@ +--- +description: Olares 新手上路指南，包括系统初始配置、基础功能和核心特性的使用方法。 +--- + +# 探索 Olares + +现在，你可以开始探索 Olares 的强大功能了。你会发现使用 Olares 可以轻松完成各项事务。 + +以下是一些建议的后续步骤： + +
+ + + + + + +
+ + diff --git a/docs/zh/manual/get-started/reusables.md b/docs/zh/manual/get-started/reusables.md new file mode 100644 index 000000000..c12147951 --- /dev/null +++ b/docs/zh/manual/get-started/reusables.md @@ -0,0 +1,38 @@ +--- +search: false +--- + +```bash +curl -fsSL https://cn.olares.sh | bash - +``` + +:::tip root 用户密码 +安装过程中，可能需要输入 root 用户密码。 +::: + +:::info 安装遇到报错？ +如果安装过程中出现错误，请先执行以下命令卸载： + +```bash +olares-cli uninstall --all + +``` + +卸载完成后，重新运行安装命令进行安装。 +::: + +## 配置 Wizard + +在安装 Olares 的核心服务之前，需要输入在 LarePass 中注册的 Olares ID 前缀。如果你的 Olares ID 为 `alice123@olares.cn`，输入 `alice123` 即可。 + +![输入 Olares ID](/images/zh/manual/get-started/enter-olares-id.png) + +安装完成后，屏幕将显示初始系统信息，包括向导地址和初始一次性密码。这些信息在后续激活步骤中会用到。 + +![Wizard URL](/images/manual/get-started/wizard-url-and-login-password.png) + +## 下一步：安全保存 Olares ID + +你已经准备好开始使用 Olares！在此之前，请务必确保 Olares ID 已安全备份。如果不备份，你将无法在需要时恢复 Olares ID。 + +- [备份助记词](../larepass/back-up-mnemonics.md) diff --git a/docs/zh/manual/glossary.md b/docs/zh/manual/glossary.md new file mode 100644 index 000000000..bf57577d0 --- /dev/null +++ b/docs/zh/manual/glossary.md @@ -0,0 +1,39 @@ +--- +description: Olares 专业术语词汇表，提供系统中常见技术概念的标准定义和解释。按字母顺序排列，便于查找和理解 Olares 生态中的专业术语。 +--- +# Glossary +
+ C + | + D + | + F + | + T + | + V +
+ +## C +### CNAME Record +CNAME（规范名称）记录是 DNS（域名系统）记录的一种，用于将自定义域名映射到 Olares 提供的地址，从而实现域名到应用的映射。 + +## D +### DID +去中心化标识符（DID）是一种独特的数字身份识别方法，可以让任何个人或实体在网络上拥有持久且唯一的身份标识。这种标识符完全独立，无需通过中心化机构进行验证或注册。DID 是一个以“did”开头的特定格式字符串，遵循既定的格式和命名规范。 + +## F +### FRP +快速反向代理（FRP）是一款专为内网穿透场景设计的高性能反向代理工具。它使位于 NAT 或防火墙后的服务器即使没有公网 IP，也能对外提供服务。通过 FRP，用户可以轻松地将内部服务暴露到公网。 + +## T +### TOTP +基于时间的一次性密码（TOTP）是一种用于生成一次性密码的时间相关算法，在双因素认证（2FA）中广泛使用。它通过共享密钥和当前时间生成一次性密码，以加强账户安全性。每个密码仅在短时间内（通常是 30 或 60 秒）有效，之后系统会生成新的密码。 + +## V +### VC +可验证凭证（VC）是一种数字化的证明格式，可以验证持有者的特定属性或资质，同时不会泄露额外的个人信息。它涉及三个主要角色： + +* 持有者：拥有并使用凭证来证明特定信息的个人 +* 颁发者：创建和签发可验证凭证的权威机构或实体 +* 验证者：需要通过验证凭证来确认持有者信息真实性的个人或组织 \ No newline at end of file diff --git a/docs/zh/manual/help/faqs.md b/docs/zh/manual/help/faqs.md new file mode 100644 index 000000000..a623e3989 --- /dev/null +++ b/docs/zh/manual/help/faqs.md @@ -0,0 +1,105 @@ +--- +description: 获取关于 Olares 的常见问题解答。 +--- +# 常见问题 + +## Olares 采用了什么协议？ + +Olares 由一系列项目组成，采用了分层授权的方式，基本原则是： + +- 区块链上运行的项目，采用 Apache 2.0，例如 [Snowinning Protocol](https://github.com/beclab/olaresdid-contract-system)。 +- 协议相关的项目，采用 Apache 2.0，例如 [r4](https://github.com/beclab/r4)。 +- Olares 和 LarePass 相关的项目，采用 Olares License。 +- 在 Olares 上运行的第三方应用，由开发者自己决定开源与否与协议选择。 + +- 每个项目具体的情况，可以在 [GitHub](https://github.com/beclab) 上查询。 + +## Olares 许可证是开源许可证吗？ + +Olares 主要项目的许可证选择受到了 [fair code](https://faircode.io/) 的启发。[Olares 许可证](https://github.com/beclab/Olares/blob/main/LICENSE.md)同样遵循以下原则: + +> - 可供任何人免费使用和分发 +> - 源代码公开可见 +> - 任何人都可以在公共和私有社区中进行扩展 +> - 作者对商业使用有所限制 + +## 如果助记词丢失了为什么不能恢复账号？ + +从 1Password 的主密钥到加密钱包的助记词，十多年来助记词存储这个问题一直没有很好的解决方案。 + +Olares 的助记词会被加密存储在所有安装了 LarePass 的设备上。通常情况下，只有当所有安装了 LarePass 的设备同时丢失时，才会失去助记词。 + +安全性是我们系统设计中最重要的原则。我们会在未来继续改进，为大家提供一个在便利性和安全性之间更好平衡的解决方案。 + +## Olares 和目前运行在 NAS 上的操作系统有什么区别？ + +在 Olares（前身是 Terminus）诞生之初，市面上已经有很优秀的 NAS 操作系统，如 [Synology](https://www.synology.com/en-global/dsm/packages)、[CasaOS](https://github.com/IceWhaleTech/CasaOS) 和 [Umbrel](https://github.com/getumbrel/umbrel)。它们确实给了我们很多启发。 + +但我们认为运行在边缘端的操作系统应该能够： + +- 为多个硬件编排资源 +- 在沙箱中管理应用 + +这些功能很难通过上述基于 Docker Compose 构建的 NAS 操作系统实现。 + +同时，Olares 致力于提供一站式自托管解决方案，这已经超出了普通 NAS 操作系统的范畴。 + +## 使用 Olares 需要付费吗？ + +在自托管场景下，基本上可以免费使用 Olares。 + +但对于以下两个功能，由于成本因素，我们可能会引入合理的收费（目前都是免费提供）： + +- **备份** + + 我们为每个 Olares ID 在 Olares Space 上提供 10G 的免费备份空间。当存档大小超过这个限制时，我们会收取一定费用来支付云服务商的费用。 + +- **快速反向代理（FRP）** + + 通过本地访问 Olares 或使用 Olares VPN 基本是免费的。然而，如果你通过 Olares 提供外部服务（例如博客），流量会先转发到 FRP 服务器再到达 Olares。此种情况下： + + - 如果你使用自己的 FRP 服务，Olares 不会收取任何费用。 + - 如果你选择使用 Olares 默认的 FRP 服务，我们每月提供 2GB 的免费流量额度。对于不通过 Olares 提供外部服务的用户，这些流量通常是足够的。如果使用超出此限额，可能会产生额外费用。 + +## 什么时候支持其他语言？ + +目前我们只支持英语和简体中文。 + +实际上，我们已经在所有前端项目中完成了 i18n 的替换工作。但我们缺乏通过开源社区维护快速迭代项目的翻译资源的经验，这方面我们还在学习中。 + +## 各种“密码”之间有什么区别？ + +为了保证安全性，Olares 确实有多种密码，包括： + +- 私钥 +- LarePass 的密码： + - 手机上可以使用生物识别登录 + - 电脑和浏览器插件需要手动输入 +- Olares 首次激活使用的一次性密码 +- Olares 的登录密码 +- Olares 登录时的二次验证码 + +不用慌！日常使用时，需要输入的只是登录 Olares 时的二次验证码。 + +## 如何部署多用户应用？ + +这取决于是要对外提供服务，还是仅供内部 Olares 用户使用。 + +- 如果要对外提供服务，可以选择“**公开**”作为应用的访问入口。这样应用就可以自行管理用户注册和认证。 +- 如果只提供内部访问，可以在 Olares 上部署这类产品的集群版本。 + +对于 Gitlab，我们提供了两个移植版本：[Gitlab Pure](https://github.com/beclab/apps/tree/main/gitlabpure) 和 [Gitlab Fusion](https://github.com/RLovelett/gitlab-fusion)。 + +## 如何使用相同的 Olares ID 重新激活 Olares? + +如果你在同一台设备上重新安装了 Olares，你之前激活的 Olares 实例将无法再访问。你可以使用同一个 Olares ID 重新激活 Olares： + +:::tip 使用相同的 Olares ID 安装 +请确保在安装过程中输入了与之前完全相同的域名和 Olares ID。 +::: + +![重新激活](/images/zh/manual/help/reactivate.png) + +1. 在手机上打开 LarePass 并进入之前的账户。你应该会在顶部看到一个红色状态提示：“未发现运行中的 Olares”。 +2. 点击**了解更多**>**重新激活**，进入二维码扫描界面。 +3. 点击**扫描二维码**来扫描向导页面上的二维码并激活 Olares。 \ No newline at end of file diff --git a/docs/zh/manual/help/index.md b/docs/zh/manual/help/index.md new file mode 100644 index 000000000..69a1cef2b --- /dev/null +++ b/docs/zh/manual/help/index.md @@ -0,0 +1,3 @@ +# Help and support + +Text diff --git a/docs/zh/manual/help/request-technical-support.md b/docs/zh/manual/help/request-technical-support.md new file mode 100644 index 000000000..6594db284 --- /dev/null +++ b/docs/zh/manual/help/request-technical-support.md @@ -0,0 +1,19 @@ +--- +description: 通过 GitHub Discussion 和 Issues 获取 Olares 技术支持。 +--- +# 技术支持 + +遇到任何问题，都可以通过 GitHub 联系 Olares 团队寻求帮助。 + +如果你的 Olares 设备正在运行，可以一键导出日志文件。附上日志文件会帮助 Olares 团队排查问题。 + + +## 反馈方式 + +1. 打开 [Olares GitHub 仓库](https://github.com/beclab/Olares)，选择以下方式提交问题： + - 创建一个新的 **[Discussion](https://github.com/beclab/Olares/discussions/new?category=q-a)**（适合一般问题或需求帮助）。 + - 提交一个 **[Issue](https://github.com/beclab/Olares/issues/new)**（适合报告 Bug 或技术问题）。 +2. 简单描述遇到的问题或疑问。如果可以，尽量提供以下信息，帮助团队快速定位问题： + - 复现问题的具体步骤。 + - 错误信息或异常行为的描述。 + - 使用环境的信息（比如操作系统、Olares 版本等），导出方法参考[导出系统日志](../olares/settings/developer.md#导出系统日志) diff --git a/docs/zh/manual/help/troubleshooting-guide.md b/docs/zh/manual/help/troubleshooting-guide.md new file mode 100644 index 000000000..1a10f3781 --- /dev/null +++ b/docs/zh/manual/help/troubleshooting-guide.md @@ -0,0 +1,3 @@ +# Troubleshooting guide + +Text diff --git a/docs/zh/manual/larepass/activate-olares.md b/docs/zh/manual/larepass/activate-olares.md new file mode 100644 index 000000000..60d2ef4ac --- /dev/null +++ b/docs/zh/manual/larepass/activate-olares.md @@ -0,0 +1,61 @@ +--- +description: 了解如何首次激活 Olares、在重新安装后重新激活，以及使用 LarePass 移动端完成安全的双因素登录。 +--- + +# 激活 Olares + +Olares 通过 **Olares ID** 与 **LarePass 移动应用**提供安全且流畅的身份验证体验。本文介绍如何激活 Olares，并在登录时使用 LarePass 完成双因素验证。 + +:::warning 管理员网络要求 +为避免激活失败，管理员用户需确保手机和 Olares 设备连接到同一网络。 +::: + +## 首次激活 + +完成 [Olares 安装向导](../get-started/install-olares.md#安装-olares-1)后，可在 **LarePass** 中使用 Olares ID 激活实例。 + +:::tip Note +新成员用户无需本地安装 Olares 即可通过激活向导激活账户。 +详细请参阅[创建成员](../olares/settings/manage-team.md#创建新成员)。 +::: + +![激活](/images/manual/larepass/activate-olares.png#bordered) + +1. 打开 LarePass。 +2. 点击 **扫码**，扫描安装向导中的二维码。 +3. 按照 LarePass 指引重置 Olares 登录密码。 + +激活成功后，LarePass 将返回主页，安装向导将跳转至登录页。 + +## 使用同一 Olares ID 重新激活 + +如果重新安装了 Olares，仍然想用原有 Olares ID 重新激活： + +1. 在手机上打开 LarePass，看到红色提示 “未发现运行中的Olares”。 +2. 点击**了解更多** > **重新激活**，进入扫码界面。 +3. 点击**扫码**，扫描安装向导中的二维码以激活新实例。 + +## 使用 LarePass 进行双因素验证 + +登录 Olares 时，需要完成双因素验证。你可以在 LarePass 中直接确认，或手动输入 6 位验证码。 + + +### 在 LarePass 中确认登录 +![2FA](/images/manual/larepass/second-confirmation.png#bordered) + +1. 在手机上打开登录通知。 +2. 点击 **确认** 完成登录。 + +### 手动输入验证码 +![OTP](/images/manual/larepass/otp-larepass.jpg#bordered) + +1. 在安装向导页面选择 **使用 LarePass 生成的一次性密码验证**。 +2. 在手机上打开 LarePass，进入**设置**。 +3. 点击顶部的身份验证器，生成一次性验证码。 +4. 返回安装向导页面，输入验证码完成登录。 + +:::tip 提示 +验证码具有时效性，请在过期前输入；若已过期，请重新生成。 +::: + +验证成功后，你将自动跳转至 Olares 桌面。 diff --git a/docs/zh/manual/larepass/autofill.md b/docs/zh/manual/larepass/autofill.md new file mode 100644 index 000000000..855707c34 --- /dev/null +++ b/docs/zh/manual/larepass/autofill.md @@ -0,0 +1,83 @@ +--- +description: 设置和使用 LarePass 的密码自动填充功能，在所有设备上实现安全便捷的密码管理体验。 +--- +# 使用 LarePass 自动填充密码 + +密码自动填充让你无需手动输入凭据，既方便又安全。通过 LarePass，你可以将密码安全地存储在密码库中，并在所有设备上自动填充。 +## 开始之前 + +确保你的设备上已安装 LarePass 移动客户端或 Chrome 扩展程序，并使用 Olares ID 登录。 + +:::tip 提示 +要获取 LarePass 的不同下载选项，请访问 [LarePass 页面](https://olares.cn/larepass)。 +::: + +## 启用自动填充服务 + + + + + + +## 保存密码 + +当你在应用或网站中输入凭据时，LarePass 会检测该操作并提示保存密码。 + +:::info 提示 +在 iOS 上，密码无法自动保存。可以手动添加 Vault 项目或使用 Chrome 扩展。Vault 项目将在所有平台同步。 +::: + +1. 登录应用或网站。 +2. 出现提示时，点击**保存**将密码存储到 LarePass。 +3. 在详情页面或窗口中输入此 Vault 项目的名称，点击**保存**。 + +## 使用自动填充 + + + + + + \ No newline at end of file diff --git a/docs/zh/manual/larepass/back-up-mnemonics.md b/docs/zh/manual/larepass/back-up-mnemonics.md new file mode 100644 index 000000000..bd2886b26 --- /dev/null +++ b/docs/zh/manual/larepass/back-up-mnemonics.md @@ -0,0 +1,56 @@ +--- +description: 学习备份 Olares 账号助记词的正确方法，确保账号安全和数据访问权限。 +--- +# 备份助记词 +助记词是由 12 个单词组成的序列，是恢复 Olares ID 的唯一方式。如果你的设备丢失或需要导入 Olares 账号，可以使用助记词重新获得 Olares 的访问权限。 + +:::warning 安全保管助记词 +在去中心化系统中，你需要对自己的安全负责。 + +请妥善保管并确保助记词的私密性，切勿与任何人分享。这是恢复 Olares 账号的唯一方式。 +::: + +## 设置本地密码 +首次导出或备份助记词时，系统可能会提示你为 LarePass 设置本地密码。该密码仅用于解锁当前设备上的 LarePass 服务。 + +设置完成后，你可以选择开启生物识别解锁功能，通过面部识别或指纹实现更安全、便捷的访问。 +![设置本地密码](/images/manual/get-started/set-up-local-password.png) + +:::info +* 同一设备上的所有 Olares ID 共用一个 LarePass 本地密码。 +* 不同设备上安装的 LarePass 应用的本地密码相互独立，单独存储。 + ::: + +## 查看并备份助记词 +1. 打开 LarePass 应用，进入**设置** > **账号**页面。 +2. 点击**立即备份**。 +3. 阅读丢失助记词的风险提示，点击**开始**。 +4. 点击查看 12 个助记词，并输入本地密码进行身份验证。 +5. 安全记录助记词并将其存放在安全的地方。 +6. 点击**下一步**。 + :::warning 离线备份助记词 + 虽然点击**复制**可以将助记词保存到剪贴板，但这存在安全风险。为了最大程度保障安全，我们强烈建议离线备份助记词。 + ::: +7. 按正确顺序排列助记词以验证备份。 +8. 点击**完成**。 + 如果排列正确，即表示你已成功备份助记词。 + ![备份助记词](/images/manual/get-started/backup-mnemonic-phrase.png) + +## 常见问题 +### 如果我丢失了助记词会怎样？ +丢失助记词将导致严重后果： + +* 你将失去数字身份（DID）和 Olares ID 的所有权。 +* 无法访问存储在保险库中的数据。 + +为防止这种情况，我们强烈建议采取以下预防措施： + +* **离线备份**：将 12 个助记词写下来并安全保管，比如存放在保险箱中。 +* **多设备备份**：使用 LarePass 的保险库功能加密保存助记词在多个设备上。只有当所有这些设备都丢失时，你才会失去助记词。 + +### 我已经激活了 Olares，为什么在 LarePass 中查看助记词时提示密码错误？ +如果遇到密码错误，可能是因为你还没有设置本地密码。打开 LarePass 应用，进入**设置** > **安全**，设置本地密码后再尝试备份。 + +## 恭喜！ +现在你已经准备好进一步探索 Olares： +- [接下来做什么](../get-started/next-steps.md) \ No newline at end of file diff --git a/docs/zh/manual/larepass/create-account.md b/docs/zh/manual/larepass/create-account.md new file mode 100644 index 000000000..17dfaf992 --- /dev/null +++ b/docs/zh/manual/larepass/create-account.md @@ -0,0 +1,77 @@ +--- +outline: [2, 4] +description: 了解如何在 LarePass 应用中创建、导入和管理 Olares ID。 +--- + +# 创建、管理账户 + +管理 Olares 账户是 LarePass 的核心功能。如果你是新用户，需要先创建一个 Olares ID。本指南将介绍创建流程及常用的账户操作。 + +::: tip 提示 +Olares ID 仅可在 **LarePass** 移动端创建。 +::: + +## 创建 Olares ID + +开始之前，请先在手机上安装 [LarePass](https://olares.cn/larepass)。根据个人需求，可选择以下两种方式之一： + +- **快速创建**：输入符合要求且可用的名称即可创建 Olares ID（默认方式）。 +- **高级创建**：使用可验证凭证（VC）将现有可信身份（如社交账号）与 Olares ID 绑定，适用于需要更高安全性或专属域名的个人或组织用户。 + +### 快速创建 + +快速创建个人 Olares ID： + +1. 在 LarePass 中点击**创建账户**。 +2. 输入想要的 Olares ID（至少 8 个字符，仅限小写字母和数字）。 +3. 点击**继续**完成创建。 + + ![快速创建](/images/manual/larepass/create-olares-id.png) + +获得 Olares ID 后，等待 [安装 Olares](../get-started/install-olares.md) 完成，然后执行 [激活](../get-started/activate-olares.md)。 + +### 高级创建 + +::: tip VC 支持 +Olares 目前通过 Gmail 提供 VC 支持，详情参见 [Gmail Issuer Service](/developer/contribute/olares-id/verifiable-credential/olares.md#gmail-issuer-service)。 +::: + + + + + + +## 导入现有账户 + +你也可以通过导入已存在的 Olares ID 来设置账户。 + +::: tip 备份助记词 +确保已 [备份助记词](back-up-mnemonics.md)，否则无法导入。 +::: + +1. 在 LarePass 中点击**导入账户**。 +2. 输入 12 个助记词导入你的 Olares ID。 diff --git a/docs/zh/manual/larepass/index.md b/docs/zh/manual/larepass/index.md new file mode 100644 index 000000000..836c180a7 --- /dev/null +++ b/docs/zh/manual/larepass/index.md @@ -0,0 +1,83 @@ +--- +outline: [2, 3] +description: LarePass 用户文档。了解 LarePass 的核心功能与使用方法，包括账户管理、文件同步、设备与网络管理、密码管理，内容收藏等，并提供下载与安装指南。 +--- + +# LarePass 使用文档 + +**LarePass** 是 Olares 的官方跨平台客户端，为用户与 Olares 系统之间建立安全桥梁。无论是移动端、桌面端还是浏览器，你都可以随时随地借助 LarePass 实现无缝访问、身份、密码管理、文件同步、内容管理。 + +![LarePass](/images/manual/larepass/larepass.png) + +## 主要功能 + +### 账户与身份管理 +创建和管理 Olares ID，安全备份凭证并连接外部服务。 +- [创建 Olares ID](create-account.md) +- [备份助记词](back-up-mnemonics.md) +- [设置或重置本地密码](back-up-mnemonics.md#设置本地密码) +- [管理集成服务](integrations.md) + +### 启用专用网络 +随时随地通过 LarePass 专用网络访问 Olares。 +- [打开专用网络](private-network.md#在-larepass-中启用专用网络) +- [排查连接问题](private-network.md#故障排查) + +### 设备管理 +激活并管理 Olares 设备，通过 LarePass VPN 安全连接。 +- [激活 Olares 设备](activate-olares.md) +- [双因素登录 Olares](activate-olares.md#使用-larepass-进行双因素验证) +- [管理 Olares](manage-olares.md) +- [切换有线/无线网络](manage-olares.md#有线切换至无线) + +### 安全文件访问与同步 +跨设备访问并同步 Olares 文件。 +- [使用 LarePass 管理文件](manage-files.md) +- [同步与共享文件](sync-share.md) + +### 密码与密钥管理 +使用 Vault 自动填充凭证、存储密码并生成 2FA 代码。 +- [自动填充密码](autofill.md) +- [生成 2FA 代码](two-factor-verification.md) + +### 知识收藏 +通过 LarePass 收集网页内容并订阅 RSS。 +- [通过 LarePass 扩展收集内容](manage-knowledge.md#通过-larepass-扩展收集内容) +- [订阅 RSS 源](manage-knowledge.md#订阅-rss-源) + +--- + +## 下载与安装 LarePass + +前往 [LarePass 官网](https://www.olares.cn/larepass) 获取适用于你设备的最新版本。 + +### 安装 LarePass 浏览器扩展 + + + + + + + +::: tip 快速访问 +安装完成后，可在 Chrome 扩展菜单中固定 LarePass，方便一键启动。 +::: diff --git a/docs/zh/manual/larepass/integrations.md b/docs/zh/manual/larepass/integrations.md new file mode 100644 index 000000000..adc750b2b --- /dev/null +++ b/docs/zh/manual/larepass/integrations.md @@ -0,0 +1,75 @@ +--- +outline: [2, 3] +description: 将 Olares Space 与第三方服务连接，扩展系统功能。了解如何集成、授权并管理已连接的服务，实现数据的无缝同步。 +--- + +# 在 LarePass 中管理集成 + +**LarePass** 是连接 Olares 与外部服务的集中枢纽，支持接入 **Olares Space**，以及 Google Drive、Dropbox、AWS S3、腾讯 COS 等三方服务。通过这些集成，你可以实现文件同步、安全备份等功能，进一步扩展 Olares 的能力。 + +:::info +我们正持续支持更多第三方集成，敬请关注！ +::: + +## 连接 Olares Space + +**Olares Space** 是 Olares 的云托管服务，使用与 LarePass、Olares 相同的账户体系。 + +### 步骤 1：登录 Olares Space + +1. 在浏览器访问 +2. 打开手机上的 LarePass。 +3. 在**设置**页面点击右上角 **扫码**图标。 +4. 扫描 Olares Space 登录页的二维码。 +5. 确认风险提示并完成登录。 + +### 步骤 2：授权 Olares Space + +1. 于 LarePass 中进入**设置** > **集成**。 +2. 点击右上角 add，选择 **Space** 以添加 Olares Space 账户。 + +### 步骤 3：关联 Olares ID + +关联 Olares ID 后，可导入区块链钱包，在个人资料中使用 NFT 头像。 + +1. 打开 Dock / 启动台中的**设置**应用。 +2. 选择左侧**集成**。 +3. 在右侧点击 Olares Space 卡片查看详情。 +4. 点击**绑定**，LarePass 会弹出确认提示。 +5. 在手机端打开 LarePass： + - 若已弹出提示，点击**确认**； + - 如未出现提示，可手动进入**设置** > **集成**，再点击 Olares Space 卡片并确认。 +6. 返回 Olares，点击**确认**完成关联。 + +## 通过 OAuth 添加云盘 + +Google Drive、Dropbox 等通过 OAuth 登录的服务集成需在 LarePass 移动端完成授权： + +1. 在手机上打开 LarePass。 +2. 依次点击**设置** > **集成**，再点右上角 add。 +3. 选择 **Google Drive** 或 **Dropbox**。 +4. 按提示登录并授权。 + +授权成功后，集成将显示在列表中，并可在**文件管理器** > **云存储**中访问存储。 + +## 通过 API 密钥添加云盘 + +AWS S3、腾讯云 COS 等服务需使用 Access Key & Secret Key 手动配置，可在 LarePass 手机端或 Olares **设置**中完成： + +1. 在手机上打开 LarePass。 +2. 进入**设置** > **集成**，点击右上角 add。 +3. 选择 **AWS S3** 或 **Tencent COS**。 +4. 输入 Access Key、Secret Key 及其他必要信息，点击**确认**。 + +配置成功后，服务将显示在集成列表，可通过**文件管理器** > **云存储**应用访问。 +你也可以在 [Olares 设置](/zh/manual/olares/settings/integrations.md) 中直接配置。 + +## 断开集成 + +:::warning +断开 Olares Space 可能影响设备管理及云备份访问，你可在需要时重新连接。 +::: + +1. 打开 LarePass，进入**设置** > **集成**。 +2. 点击要移除的集成。 +3. 点击右上角 more_horiz，选择**删除**。 diff --git a/docs/zh/manual/larepass/manage-files.md b/docs/zh/manual/larepass/manage-files.md new file mode 100644 index 000000000..3e0d3589d --- /dev/null +++ b/docs/zh/manual/larepass/manage-files.md @@ -0,0 +1,107 @@ +--- +description: 了解如何在 LarePass 桌面端和手机端中执行常用文件操作，包括上传、编辑、删除、下载等。 +--- + +# LarePass 常用文件操作 + +在 **LarePass** 中管理文件与**文件管理器**应用体验一致，不同平台之间仅有细微差异。本文将带你快速上手 LarePass 中的常见文件任务。 + +## 上传文件 + +通过 LarePass 上传的文件会自动同步到同一账户下的 Olares。 + +### 通过 LarePass 桌面端上传 + +:::info 导入 Olares ID +首次使用 LarePass 桌面端需粘贴助记词导入 Olares ID。请确保已 [备份助记词](back-up-mnemonics.md)。 +::: + +LarePass 桌面端提供与文件管理器应用相同的上传体验，并自动同步至 Olares。 + +### 通过 LarePass 移动端上传 + +你也可以在手机上通过 LarePass 上传文件。 + + + + + + + +## 下载文件 + +在 LarePass 中批量下载文件时，任务将排队执行，可随时暂停、继续或取消，并能快速定位已下载文件。 + +:::tip 建议 +下载大文件或批量下载时，推荐使用 LarePass 桌面端以获得更强的下载管理能力和更佳体验。 +::: + + + + + + +## 删除文件 + +:::warning +删除操作不可恢复，请谨慎操作。 +::: + + + + + + diff --git a/docs/zh/manual/larepass/manage-knowledge.md b/docs/zh/manual/larepass/manage-knowledge.md new file mode 100644 index 000000000..f476d6d82 --- /dev/null +++ b/docs/zh/manual/larepass/manage-knowledge.md @@ -0,0 +1,78 @@ +--- +description: 使用 LarePass 在多设备间收集网页内容、视频和 RSS 源。 +--- + +# 使用 LarePass 收藏内容 + +LarePass 让你轻松收集并管理来自网络的各种信息——无论是文章、播客、视频还是 RSS 源。通过浏览器扩展和移动端应用，只需几次点击即可完成内容收集，并无缝同步至 Olares 的知识管理应用 Wise。 + +本文将介绍如何使用LarePass 扩展和移动客户端收集内容，以及如何订阅 RSS 源以持续获取更新。 +关于内容整理与使用，请参阅 [Wise 文档](../olares/wise/)。 + +## 准备工作 + +开始收集网页内容前，请确保： + +- Olares 设备已启动 +- 手机已安装 LarePass +- 已在 Chrome 中 [安装 LarePass 浏览器扩展](index.md#安装-larepass-浏览器扩展) + +## 通过 LarePass 扩展收集内容 + +浏览器扩展是内容发现与收集的核心工具。 + +::: tip 上传 Cookies 获得更好体验 +某些网站对匿名用户有限制，可上传浏览器 Cookie 至 Olares 以提升抓取成功率。 + +1. 登录目标网站并打开LarePass 扩展。 +2. 进入**收集** > **Cookie**，点击**上传**。 +3. 悬停查看每个 Cookie 详情，如需排除点击 **X** 即可。 +::: + +收集网页内容流程： + +1. 访问目标页面（例如 CNN 文章）。 +2. 打开 LarePass 扩展，系统会自动检测可收集内容。 +3. 在**收集** > **页面**中，点击标题旁的 add_box 将页面添加至 Wise。 + + ![Collect web content](/images/manual/tutorials/wise-collect-web-content.png#bordered) + +收集完成的内容将出现在 Wise 的**库** > **文章**中，相关媒体文件（图片、视频、音频）保存至 `/download/Wise/Article`。 + +## 通过 LarePass 应用收集内容 + +你也可在移动浏览器中直接分享内容到 LarePass。 + +:::info +步骤因设备与浏览器而异，以下示例基于 iOS Safari。 +::: + +1. 在浏览器中点击 ios_share **分享** 按钮： + - 从菜单中选择 **LarePass**，或 + - 点击**更多操作** 并选择 **LarePass**。 + + ![Share to Wise](/images/manual/tutorials/wise-add-articles-via-share.png#bordered) + +2. 跳转至 LarePass 应用后，系统会自动识别可收集内容并提示添加至 Wise。 +3. 点击**确认**完成收集。 + +::: tip 复制链接快速分享 +也可复制网址后直接打开 LarePass，它会自动检测剪贴板中的 URL 并提示收集。 +::: + +添加成功的内容同样会出现在 **Wise** 的**库** > **文章**中。 + +## 订阅 RSS 源 + +LarePass 支持 RSS 订阅，轻松跟踪播客、博客等内容源。 + +通过 LarePass 浏览器扩展订阅： + +1. 访问 RSS 源或播客页面（如 `https://www.spreaker.com/podcast/paranormal-mysteries--2321086`）。 +2. 打开 **LarePass 扩展**，系统会自动检测并显示 **RSS** 选项卡。 +3. 点击想要订阅的源旁的 bookmark_add 即可订阅。 + + ![Subscribe to podcast](/images/manual/tutorials/wise-sub-podcast.png#bordered) + +已订阅的源将同步至 Wise，所有新内容可在同一位置集中查看。 +``` diff --git a/docs/zh/manual/larepass/manage-olares.md b/docs/zh/manual/larepass/manage-olares.md new file mode 100644 index 000000000..35cf28ef3 --- /dev/null +++ b/docs/zh/manual/larepass/manage-olares.md @@ -0,0 +1,104 @@ +--- +description: 使用 LarePass 移动端远程管理 Olares，包括监控状态、网络配置、远程控制与设备信息查看。 +--- + +# 使用 LarePass 管理 Olares + +**LarePass** 应用让你在手机端即可远程管理 Olares 设备：监控系统状态、配置网络、执行远程控制，并查看关键设备信息。 + +## 前提条件 + +开始前，请确认： + +- 已拥有有效的 **Olares ID**，且 Olares 设备已激活。 +- Olares 设备已通电并连接网络。 +- 手机与 Olares 设备位于同一局域网。 +- 当前账户具备管理员权限。 + +## 进入 Olares 管理界面 + +1. 打开 LarePass，进入**设置**。 +2. 点击你的 **Olares ID**，进入 Olares 管理页面。 + +## 远程设备控制 + +在 Olares 管理页右上角点击 power_settings_new，可执行： + + ![控制设备](/images/zh/manual/larepass/device-control.png) +- **重启 Olares** – 设备将重启，状态显示 `正在重启`，约 5–8 分钟后恢复为 `Olares 运行中`。 +- **关闭 Olares** – 设备关机，状态显示 `Olares 已关机`，需手动开机。 + +## 网络配置 + +你可以在**Wi-Fi 配置**页面查看或变更当前网络设置。 + +### 有线切换至无线 + +若 Olares 通过有线网络激活，可用 LarePass 切换至同一网络的 Wi-Fi： + +![Wi-Fi 切换](/images/zh/manual/larepass/switch-wifi.png) + +1. 在 Olares 管理页面，点击**Wi-Fi 配置**选项，进入**选择连接方式**页面。 +2. 点击列表里的 Wi-Fi 网络以连接。 若 Wi-Fi 有密码，在弹出窗口里输入密码并确认。 +3. 连接成功后，网络自动切换至 Wi-Fi，过程大概会持续 5 分钟。Olares 状态首先会显示 `IP 地址变更中`，切换完成后恢复 `Olares 运行中`。 + +切换后，你可以用同样的步骤切换回有线网络。 + +::: tip 建议 +为获得最佳稳定性，优先使用有线网络。 +::: + +### 更新 IP 地址 + +当 Olares 迁移至新网络： + +1. 将 Olares 接入有线网络并开机，并将手机接入同一网络的 Wi-Fi。 +2. 打开 LarePass，进入 **Olares 管理**。 +3. LarePass 会自动扫描局域网中的 Olares，找到后状态显示 `IP 地址变更中`。 +4. IP 更新完成后，状态变为 `Olares 运行中`，约需 5–10 分钟。 + +### 蓝牙配网 + +如果在激活 Olares 时无法连接有线网络，或者 Olares 连接到的有线网络与你的手机网络不同，LarePass 在局域网里无法发现 Olares，你也无法顺利完成激活或设备管理。在这种情况下，可使用蓝牙配网功能将 Olares 连接到你手机的 Wi-Fi 网络。 + +![蓝牙配网](/images/zh/manual/larepass/bluetooth-network.png) + +1. 在**未发现 Olares**提示页面底部，点击**蓝牙配网**选项。LarePass 将使用手机蓝牙扫描与当前登录账号匹配的 Olares 设备。 + +2. 找到设备后，点击**配置网络**。 + +3. 从 Olares 可用的无线网络列表中，点击你手机当前连接的 Wi-Fi 网络。如果该网络有密码保护，请输入密码并点击**确认**。 + + ::: tip 注意 + 如果你选择的 Wi-Fi 网络与手机不同，连接后 LarePass 仍将无法识别你的 Olares 设备。 + ::: +4. Olares 将开始网络切换过程。完成后您会看到成功消息。此时，如返回到**蓝牙配网**页面，你将看到 Olares 的 IP 地址已更改为你手机 Wi-Fi 一样的网络。 + + ::: tip 注意 + 如果你的 Olares 之前已激活，此过程将耗时更长，因为网络切换会影响更多服务。 + ::: + +5. 返回到设备扫描页面，现在应该可以找到你的 Olares 设备了。你可以继续[激活设备](activate-olares.md)或执行本文档里的设备管理操作。 + +## 查看设备信息 + +点击管理页顶部的设备信息区域，可查看以下设备信息： + +- 硬件详情 +- 系统版本 +- 资源使用情况 +- 当前网络连接 + +## 卸载 Olares + +此操作会将设备恢复到待安装状态，届时可在局域网重新扫描、安装并激活 Olares。 +![卸载 Olares](/images/manual/larepass/restore-to-factory.png) + +::: warning 谨慎操作 +该操作将永久删除所有账户信息与数据。 +::: + +1. 在**Olares 管理**页面点击**恢复出厂设置**。 +2. 阅读风险提示，并输入 LarePass 本地锁屏密码；若未设置，将提示先创建。 +3. 等待卸载完成，系统将返回 Olares ID 登录界面。 + diff --git a/docs/zh/manual/larepass/private-network.md b/docs/zh/manual/larepass/private-network.md new file mode 100644 index 000000000..005836eaa --- /dev/null +++ b/docs/zh/manual/larepass/private-network.md @@ -0,0 +1,84 @@ +--- +outline: [2, 3] +description: 使用 LarePass 专用网络从任何地点安全访问 Olares。了解专用网络的启用方法以及常见故障排查。 +--- +# 通过专用网络随时随地访问 Olares + +启用 LarePass 专用网络会创建一个安全的专用通道，让你随时随地安全、快速访问你运行在 Olares 上的应用和服务。 + +本文将介绍如何在不同设备上启用 LarePass 专用网络。 + + +## 了解 Olares 上的应用访问 + +在 Olares 中，您可以通过专属网址（`app.yourname.olares.com`）访问应用和服务。根据应用的访问属性，入口可分为两种类型： + +* 公共入口 (Public entrance): 无需身份验证即可供任何人访问。例如，你托管在 WordPress 上的博客页面。流量在到达 Olares 之前会通过 Cloudflare Tunnel 或 FRP 进行路由转发。 +* 私有入口 (Private entrance): 仅供你个人使用，例如访问您的桌面、Vault 或 WordPress 管理后台等服务。访问私有入口时存在两种情况： + * 启用 LarePass 专用网络时: 无论你身在何处，流量都将通过基于 Tailscale 的专用网络到达 Olares。 + * 未启用 LarePass 专用网络时: 流量的路由方式与公共入口相同。 + +::: warning 始终启用 LarePass 专用网络 +为获得最佳体验，我们强烈建议你在访问 Olares 时启用 LarePass 专用网络。这能确保你对应用的连接始终保持安全、高效。 +::: + +::: tip 注意 +从 Olares 1.12 版本开始，你不再需要为本地访问使用单独的 `.local` 地址 (如 `app.local.yourname.olares.cn`)。只要 LarePass 专用网络处于激活状态，你的唯一应用地址 (`app.yourname.olares.cn`）会自动为你提供快速、安全的连接。 +::: + +## 在 LarePass 中启用专用网络 + +::: tip +查看各平台安装包，请访问[官方下载页面](https://olares.com/larepass)。 +::: + +![VPN](/images/manual/larepass/vpn.jpg) + +### LarePass 移动端 + +1. 打开 LarePass，依次进入**设置** > **账户**。 +2. 打开**专用网络**开关。 + +### LarePass 桌面端 + +1. 打开 LarePass，点击主界面左上角头像区域。 +2. 在弹出面板中打开**专用网络**开关。 + +启用专用网络后，无论使用 LarePass 客户端还是浏览器，设备都会通过专用网络访问 Olares。 + +::: info +在 iOS 或 macOS 上首次开启专用网络时，系统会提示添加专用网络配置文件，请按指引完成。 +::: + +## 了解连接状态 + +LarePass 会展示设备到 Olares 的连接状态，帮助你判断或诊断网络情况。 + +![连接状态](/images/manual/larepass/connection-status.jpg) + +| 状态 | 描述 | +|--------------|--------------------------------------------------------| +| Internet | 通过公网连接到 Olares | +| Intranet | 通过局域网连接到 Olares | +| FRP | 通过 FRP 连接到 Olares | +| DERP | 通过专用网络使用 DERP 中继服务器连接到 Olares | +| P2P | 通过专用网络使用点对点 (P2P) 连接到 Olares | +| Offline mode | 当前离线，无法连接到 Olares | + +::: info +若在外网环境使用专用网络访问私有入口时，连接状态显示 **DERP**，说明专用网络无法直接通过 P2P 连接 Olares，需要借助 Tailscale 中继服务器，这可能影响连接质量。如长期如此，请联系 Olares 支持。 +::: + +## 故障排查 + +出现连接问题时，LarePass 会显示诊断信息。常见提示及处理办法如下： + +![异常消息](/images/zh/manual/larepass/abnormal-state.jpg) + +| 状态提示 | 可能原因与解决方案 | +|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| 检测到网络问题，请检查本地网络设置。 | **本地网络异常**
1. 等待自动重连，系统会在网络恢复后同步数据。
2. 若问题持续，检查本地网络设置。 | +| 需要专用网络连接至 Olares。 | **未开启专用网络**
点击通知横幅并按提示开启专用网络。 | +| 需要重新登录 Olares。 | **会话过期或认证问题**
点击通知横幅并按提示重新登录。 | +| 需要重新连接到 Olares。 | **连接中断或超时**
点击通知横幅并按提示重新登录，登录后 Vault 数据将与服务器同步合并。 | +| 无活跃 Olares。 | **临时网络问题或 Olares 正在重启/关机**
等待自动恢复，通常会很快解决。
**Olares 实例已不存在**
1. 点击通知横幅并按提示重新激活 Olares、启用离线模式或忽略通知。
2. 若问题持续，请联系 Olares 管理员。 | diff --git a/docs/zh/manual/larepass/sync-share.md b/docs/zh/manual/larepass/sync-share.md new file mode 100644 index 000000000..2562b68d4 --- /dev/null +++ b/docs/zh/manual/larepass/sync-share.md @@ -0,0 +1,137 @@ +--- +outline: [2, 3] +description: 使用 Olares 中文件管理器的同步和共享功能，设置跨设备同步和管理共享权限，提升团队协作效率。 +--- + +# 同步和共享文件 + +本页面主要介绍： +- 如何跨设备同步文件 +- 如何与团队成员共享文件 + +## 了解同步和库 + +### 同步 + +文件管理器应用中的同步功能类似于 iCloud 等云存储服务，帮助你将最重要的信息保持最新，并可在所有设备上访问。同步功能还简化了在 Olares 集群内与其他成员共享文件的操作。 + +### 库（Library） + +库是组织、同步和共享数字内容的基本单元。它是一个多功能的文件容器，可满足各种数据同步和共享需求： + +* **多设备同步**：库确保你的数据在所有设备上保持一致。 +* **实时协作**：与其他用户共享库，在同一库内实现数据的同时访问和编辑。 +* **灵活管理**：创建多个库以组织不同类型的数据或用于不同项目，提供对同步和共享偏好的精细控制。 + +### 角色与权限 + +:::tip 提示 +此处描述的角色与权限仅适用于文件管理器中的文件共享和库管理，与 Olares 的整体用户角色和系统权限不同。 +::: + +| 操作 | 所有者 | 成员 | +|--------------------------|-------|------| +| 创建库 | ✅ | ✅ | +| 管理库权限 | ✅ | ❌ | +| 邀请其他成员 | ✅ | ❌ | +| 共享并重命名库 | ✅ | ❌ | +| 移除成员 | ✅ | ❌ | +| 删除库 | ✅ | ❌ | +| 退出库 | ❌ | ✅ | + +权限级别： +- **只读**：用户可以查看库内容，但无法修改。 +- **读写**：用户可以添加、删除和修改库内容。 + +## 开始之前 + +请确保你已从 [官方网站](https://olares.cn/larepass) 安装 LarePass 桌面客户端，并使用你的 Olares ID 登录。 + +:::tip 提示 +目前，本地文件同步支持 Windows 和 Mac 设备。本文档以 Mac 为例。 +::: + +## 创建库 + +每位用户都会自动获得一个个人库作为起点。要创建新库： + +1. 在**同步盘**下的左侧边栏中，点击 add_circle 打开**新建库**对话框。 +2. 输入库名称并点击**创建**。 + +## 将库文件同步到本地 + +1. 在 Mac 上打开 LarePass。 +2. 找到目标库，点击 more_horiz > **同步到本地**。 +3. 选择首选的本地目录并点击 **完成**。 +4. 要启动同步，点击 more_horiz > **立即同步**。 + +同步完成后，库将显示绿色图标，表示处于双向同步状态。任何本地更改都会自动反映在同步的库中。 + +## 将本地文件同步到库 + +:::tip 提示 +如果你对库只有只读权限，就无法将本地文件夹的更改同步到资料库。新添加和修改的文件将为只读状态，用灰色禁用图标 remove 表示。 +::: + +要同步 Mac 上的现有本地文件夹，只需在 LarePass 中创建一个匹配的库，并将文件移动到指定的同步目录中。 + +这种方法允许你保留当前的文件夹结构，同时支持 LarePass 的同步功能。 + +## 管理同步设置 + +如果需要暂停或停止特定库的同步： + +1. 在 LarePass 中找到该库。 +2. 点击 more_horiz > **取消同步**。 + +此操作不会删除本地文件，只是停止双向同步过程。 + +## 共享库 + +:::tip 提示 +要在 Olares 中添加成员，请参阅 [管理用户](../olares/settings/manage-team.md)。 +::: + +你可以与 Olares 服务器中的其他成员共享库： + +1. 选择一个库，点击 more_horiz > **共享**。 +2. 在对话框中，从下拉菜单中选择用户，点 **共享用户**。 +3. 为每位用户设置文件权限：**读写**或**只读**。 +4. 点击**关闭**。 + + ![Share library](/images/manual/olares/share-library.png#bordered){width="50%"} + +被邀请的用户将在其同步内容列表中看到共享库。要撤销共享权限，只需从共享窗口中移除该用户。 + +## 退出或删除库 + +如果你不再希望共享库，可以选择退出共享或删除库。 + +- **退出共享**：任何成员都可以退出共享库。如果所有者退出，共享库将出现在其个人库列表中。 +- **删除库**：只有所有者可以删除共享库。 + + :::warning 警告 + 删除库是不可逆的。共享库中的所有文件将被永久删除。 + ::: + +1. 要退出库： + + a. 选择一个共享库，点击 more_horiz > **退出共享**。 + + b. 在弹出对话框中点击**确认**。 +2. 要删除库： + + a. 选择一个共享库，点击 more_horiz > **删除**。 + + b. 在弹出对话框中点击**确认**。 + +## 处理同步冲突 + +在极少数情况下，可能会出现同步冲突。当多个设备同时编辑同一文件时： + +* 第一个完成的编辑会保存到库中。 +* 冲突版本会备份，并以唯一文件名保存，包括编辑者的 Olares ID 和时间戳：`test.txt(SFConflict name 2024-04-17-12-12-12)`。 + +## 了解更多 + +- [管理用户](../olares/settings/manage-team.md) \ No newline at end of file diff --git a/docs/zh/manual/larepass/two-factor-verification.md b/docs/zh/manual/larepass/two-factor-verification.md new file mode 100644 index 000000000..b91b15128 --- /dev/null +++ b/docs/zh/manual/larepass/two-factor-verification.md @@ -0,0 +1,60 @@ +--- +description: 在 Vault 中设置和使用双因素身份验证。生成安全的 2FA 代码，增强账户安全性，实现与主流验证器的兼容。 +--- +# 生成双因素身份验证（2FA）代码 + +双因素身份验证（2FA）在登录时需要你的密码和身份验证代码。这些代码由基于时间的一次性密码（TOTP）生成，自动刷新。与 Google Authenticator 或 Microsoft Authenticator 类似，Vault 可以为你的在线账户生成安全的 2FA 代码。 + +本文档将展示如何在 Vault 中生成双因素身份验证（2FA）代码。 + +## 准备目标服务 + +1. 登录你希望启用 2FA 的网站或应用（例如 GitHub 或 OpenAI）。 +2. 转到安全设置页面，启用基于身份验证应用的双因素身份验证。 + + ![Enable GitHub 2FA](/images/manual/olares/2fa-github.png#bordered) + +3. 保存提供的密钥或二维码以备后续使用。 + +:::tip 注意 +如果服务提供恢复代码，请安全存储。这些代码在你无法访问 Vault 时对账户恢复至关重要。 +::: + +## 在 Vault 中创建身份验证器 + +:::tip 提示 +访问 [官方页面](https://olares.cn/larepass) 获取下载选项。 +::: + + + + + + + +保存后，新的身份验证器将立即开始生成代码。 + +## 使用你的 2FA 生成器 + +1. 使用你的用户名和密码登录网站。 +2. 当系统提示输入验证码时，打开 Vault 查看当前的 6 位验证码。 +3. 输入验证码完成登录。 \ No newline at end of file diff --git a/docs/zh/manual/olares-vs-nas.md b/docs/zh/manual/olares-vs-nas.md new file mode 100644 index 000000000..83e4079f8 --- /dev/null +++ b/docs/zh/manual/olares-vs-nas.md @@ -0,0 +1,111 @@ +--- +outline: [2, 3] +description: 对比 Olares 与通用 NAS 系统，展现它们在存储方案、应用生态、虚拟机支持、网络配置及 AI 能力等方面的关键区别。 +--- + +# 比较 Olares 和 NAS + + + +Olares 致力于打造一站式的自托管个人云体验。其核心功能与用户定位，均与传统 NAS 有着显著的不同。 + +本文档将对比 Olares 与通用 NAS 系统，并选取 Unraid、群晖 DSM 作为比较对象，展现它们在存储方案、应用生态、虚拟机支持、网络配置及 AI 能力等方面的关键区别，助你全面了解各方案特性和使用场景。 + +## 概览 + +| 属性 | Olares | NAS | +| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| 介绍 | Olares 是一款开源个人云操作系统。 | NAS 系统主要用于网络存储，可灵活搭配硬件，管理数据和应用。 | +| 定位 | 专注于帮助用户在本地部署和
管理数字资产，替代公有云服务。
它支持本地运行强大的开源应用
为用户提供云计算的强大能力，
同时确保数据的完全掌控和隐私安全。 | 专注于个人和小企业，解决低成本数据存储可靠性问题，但在应用托管和网络安全上有局限性。 | +| 目标用户 | 没有技术背景的普通用户 | 极客用户和中小企业用户 | +| 透明度 | 开源或代码公开 | 通常闭源 | +| 开放程度 | 无厂商锁定 | 封闭生态 | +| 应用安全 | 支持应用沙盒，隔离网络、存储和计算资源，
安装时需声明权限并获得用户授权。 | 无应用沙盒，大多数第三方应用以 root 权限运行，用户需自行承担安全风险。 | +| 网络安全 | 区分公开访问和私有访问，
采用反向代理和 VPN 机制保护服务安全性。 | 默认仅支持受限系统应用的外网访问，用户定制解决方案时存在较大安全风险。 | +| 开发者友好性 | 提供开发工具，开发者可以用熟悉的技术栈
部署服务和开发应用。 | 不支持开发者工具或应用开发。 | +| AI | 1. 先进的 GPU 管理（1.12 版）
2. 支持 30 多款 AI 应用和模型的一键安装
3. 支持应用和模型间的相互调用
4. 支持 MCP（1.12 版本） | ❌ | + +## 项目信息 + +| 属性 | Olares | Unraid | 群晖 DSM | +| ---- | ------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| 年份 | 2022 年 | 2005 年 | 2000 年 | +| 开源 | 是 | 否 | 否 | +| 价格 | 免费 | 30 天试用，之后需购买一次性付费协议 | 操作系统搭配硬件一起销售 | +| 定位 | 开源个人云操作系统，
帮助用户在本地部署和管理数字资产，替代公有云服务 | 网络存储操作系统，可灵活搭配硬件，简单便捷地管理数据、虚拟机及 Docker 应用 | 提供不同规模企业安全、高效的数据管理系统，帮助企业掌控日益增长的数据流 | + +## 存储功能 + +| 功能 | Olares | Unraid | 群晖 DSM | +| ---------------- | -------------------------------------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------- | +| 硬盘类型 | 系统空间、用户空间、应用空间
和应用缓存位于 SSD | SSD 运行系统，HDD 存放数据 | SSD 运行系统，HDD 存放数据 | +| 存储池 | ❌ | 支持类似 JOBD 的 Parity 保护阵列 | 支持 SHR、Basic、JBOD、RAID 0、RAID 1、RAID 5、RAID 6、RAID 10、RAID F1 | +| 局域网文件分享 | SMB | SMB，NFS | SMB，NFS，AFP，FTP | +| 公网文件分享 | 通过文件管理器应用 | 无官方支持 | File Station 应用 | +| 分布式文件系统 | ✅ | ❌ | ❌ | +| 挂载外部云盘 | 支持挂载 Google Drive、
Dropbox、S3 等云盘 | 无官方支持 | 支持挂载 Google Drive、Dropbox、S3 等云盘 | +| 同步盘 | ✅ （集成 Seafile） | 无官方支持 | 支持 Synology Drive | +| 挂载 SMB 目录 | ✅ | 无官方支持 | 无官方支持 | +| 挂载移动存储设备 | 自动挂载 | 手动挂载 | 自动挂载 | +| 结构化数据支持 | 支持主流数据库和数据仓库
（如 Redis、Postgresql），
可用于生产环境 | 可手动安装，但不建议用于生产环境 | 可手动安装，但不建议用于生产环境 | +| 本地数据安全 | 单节点无保护，集群模式下
可通过 Minio 或 Ceph
提供硬盘数据保护 | 根据配置允许损坏 1-2 块磁盘，但 Parity 盘不可损坏 | 根据 RAID 协议选择，允许损坏 1-2 块硬盘 | +| 异地备份 | 支持通过 Restic
进行定期增量加密备份 | 可手动备份 Flash Drive，但对数据盘无官方备份方案 | 支持多种官方备份方案 | + +## 应用管理 + +| 功能 | Olares | Unraid | 群晖 DSM | +| ---------------- | ------------------------------------------------- | ---------------------------------------- | ------------------------------ | +| 安装格式 | 基于 Helm 改进的 Olares 包格式 | Dockerfile 或 Docker Compose | Dockerfile 或 Docker Compose | +| 应用商店 | 应用丰富，支持应用沙盒 | 应用丰富，但无应用沙盒限制，存在安全隐患 | 应用较少，可通过第三方商店扩展 | +| 应用沙盒 | ✅ | ❌ | ❌ | +| 开发者工具 | 支持（Studio） | ❌ | ❌ | +| 中间件共享 | 支持 Postgresql、
MongoDB、Redis 等主流中间件 | ❌ | ❌ | +| Cluster 应用支持 | ✅ | ❌ | ❌ | +| LDAP 集成 | ✅（需第三方适配） | ❌ | ❌ | +| 统一 SSO 登录 | ✅ | ❌ | ❌ | +| Secret 管理 | ✅ | ❌ | ❌ | + +## 虚拟机管理 + +| 功能 | Olares | Unraid | 群晖 DSM | +| ------------- | --------------------------------------------------------------------- | ------------------------------ | ------------- | +| 通过 ISO 安装 | 暂不支持，将通过
kubevirt 支持 | ✅ | ✅ | +| Windows | 应用商店一键安装，自动
集成 Tailscale，实现外网
安全 RDP 访问 | 通过 ISO 安装 | 通过 ISO 安装 | +| Steam | 应用商店支持，自动完成
显卡挂载、串流和外网访问的配置 | 需要手动完成显卡直通等额外配置 | 无官方支持 | +| Linux | Studio 提供 Dev Container
形式支持 | 通过 ISO 安装 | 通过 ISO 安装 | +| Android | ✅ （redroid） | 无官方支持 | 无官方支持 | +| Mac | 即将支持 | 无官方支持 | 无官方支持 | +| Openwrt | 即将支持 | 无官方支持 | 无官方支持 | + +## 网络访问 + +| 功能 | Olares | Unraid | 群晖 DSM | +| ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | +| 反向代理 | 集成 Cloudflare Tunnel
和 FRP，支持所有应用独立域名访问 | 仅支持访问受限系统服务 | 仅支持访问受限系统服务 | +| DDNS | 无需配置 | 需要手动配置。支持使用域名+端口的方式访问非系统应用，但际上无法对外提供服务。 | 需要手动配置。支持使用域名+端口的方式访问非系统应用，但际上无法对外提供服务。 | +| 独立域名支持 | ✅ | ❌ | ❌ | +| 防火墙 | 集成 Cloudflare 防火墙 | ❌ | ❌ | +| 免费 HTTPS 证书 | ✅ | ✅ | ✅ | +| 登录二次验证 | ✅ | ✅ | ❌ | +| 对不同目录设置不同的安全策略 | ✅ | ✅ | ❌ | +| 私有访问端点 | ✅ | ✅ | ❌ | +| 私有访问端点 | ✅ | ✅ | ❌ | +| VPN 连接 | 无需配置，集成 Tailscale | 需要手动配置 | 需要手动配置 | +| 仅 VPN 访问模式 | ✅ | ❌ | ❌ | + +## AI 能力 + +| | Olares | Unraid | 群晖 DSM | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ------ | +| GPU 管理 | 1. 支持多节点下的异构 GPU 集群（1.12 版本）
2. Nvida 显卡支持内存分片，
时间分片两种显卡共享模式（1.12 版本） | 单节点下通过手工方式
支持显卡直通 | ❌ | +| 模型 | 1. 支持主流的语言，图片，视频，语音模型，
例如 Ollama、VLLM、ComfyUI、
SD，Whisper，ACE-STEP 等
2. 支持主流的开源 AI 工具，
例如 Dify，Ragflow，MaxKB，LobeChat 等 | ❌ | ❌ | +| 相互调用 | 1. 支持应用和模型间的相互调用
2. 系统级的支持 MCP 调用（1.12 版本） | ❌ | ❌ | diff --git a/docs/zh/manual/olares/collaborate.md b/docs/zh/manual/olares/collaborate.md new file mode 100644 index 000000000..0aaca48dc --- /dev/null +++ b/docs/zh/manual/olares/collaborate.md @@ -0,0 +1,45 @@ +--- +description: 了解如何在 Olares 中共享文件和密钥、设置应用入口、使用专用网络，在保护数据隐私的同时实现高效团队协作。 +--- +# 在 Olares 中协作 + +Olares 帮助团队在保持数据隐私的同时高效协作。通过以下关键功能，设置你的团队协作工作空间。 + +## 在文件中访问和共享文件 + +文件应用提供个人和共享存储空间： + +* 为团队文档和资产创建共享库。 +* 为不同团队成员设置精细的访问权限。 +* 在桌面和移动设备间无缝访问文件。 + +详情请参阅[同步和共享文件](../larepass/sync-share.md)。 + +## 在 Vault 中存储和共享敏感信息 + +Vault 让你可以在团队内存储和共享敏感数据： + +* 安全地与团队成员共享密码和凭据。 +* 为不同项目创建单独的 Vault。 +* 使用端到端加密保护敏感数据隐私。 +* 在桌面和移动设备间访问共享凭据。 + +详情请参阅[共享 Vault 项目](vault/share-vault-items.md)。 + +## 设置应用入口 + +为你的团队提供通过公共和私有入口访问应用的灵活方式。公共入口适用于面向公众的团队服务（如公开网站），而私有入口确保内部工具或资产的安全访问。你可以： + +* 使用自定义路由 ID 替换默认的路由 ID（如将 `de463205` 更改为 `team-wiki`）。 +* 设置自定义域名，方便团队访问。 + +详情请参阅[自定义应用 URL](settings/custom-app-domain.md)。 + +## 使用专用网络简化远程访问 + +当你的团队远程办公时，通常需要通过公共网络访问 Olares，涉及使用 Cloudflare 等服务和复杂的网络设置。Olares 内置专用网络，提供了更简单的解决方案： + +* 团队成员可以使用简单的本地地址，在不同设备上访问应用。 +* 连接保持在内部网络中，而无需通过公共网络，从而提高访问速度，降低公共网络使用成本。 + +详情请参阅[通过专用网络随时随地访问 Olares 应用](../larepass/private-network.md)。 \ No newline at end of file diff --git a/docs/zh/manual/olares/controlhub/edit-resource.md b/docs/zh/manual/olares/controlhub/edit-resource.md new file mode 100644 index 000000000..e72fda6a2 --- /dev/null +++ b/docs/zh/manual/olares/controlhub/edit-resource.md @@ -0,0 +1,34 @@ +--- +description: 通过 Olares 控制面板修改系统资源配置。学习编辑 YAML 文件、调整 Pod 副本数量、查看容器状态。 +--- +# 通过控制面板修改系统资源 + +本文档介绍如何编辑 Olares 环境中的资源配置。 + +:::warning 警告 +修改系统资源可能会显著影响系统的稳定性和性能。请谨慎操作，在专业指导下进行修改。 +::: + +## 编辑 YAML 文件 + +要编辑 Olares 工作负载的 YAML 配置文件： + +1. 在**控制面板**中，进入应用的**部署**列表，点击资源以展开其详细信息视图。 +2. 在页面右上角，点击 **more_vert** > **编辑 YAML** 打开 YAML 编辑器。 +3. 根据需要编辑工作负载的 YAML 配置。 +4. 点击**确认**保存更改并应用配置。 + + ![编辑 YAML](/images/how-to/olares/controlhub/browse/10.jpg#bordered) + +## 修改 Pod 副本数 + +要修改运行中的 Pod 副本数量： + +1. 在**控制面板**中，进入 Pod 资源详情页，查看顶部显示的 Pod 副本数量。 +2. 点击 **add** 或 **remove** 调整 Pod 副本数量。 + + ![副本数量](/images/how-to/olares/controlhub/browse/09.jpg#bordered) + +:::warning 警告 +Olares 中的许多应用不支持多副本模式。增加这些 Pod 的副本数量可能会导致异常。因此，请务必仔细阅读文档，并谨慎调整副本数量。 +::: diff --git a/docs/zh/manual/olares/controlhub/index.md b/docs/zh/manual/olares/controlhub/index.md new file mode 100644 index 000000000..8d71a642b --- /dev/null +++ b/docs/zh/manual/olares/controlhub/index.md @@ -0,0 +1,29 @@ +--- +outline: [2, 3] +description: 熟悉 Olares 中控制面板应用的操作界面，了解如何导航资源视图、管理工作负载和服务等。 +--- + +# 通过控制面板管理 Olares + +**控制面板**是 Olares 的控制台，为开发者和用户提供对系统操作和底层环境的精准控制。本文档将帮助你了解控制面板的界面并高效监控资源。 + +## 导航 + +### Olares + +通过以下三种视图监控应用的状态： + +- **浏览**（以应用为中心）：通过三列布局导航与特定应用相关的资源使用情况，高效定位资源。 +- **命名空间**（以用户为中心）：访问每位用户的应用资源使用情况的详细信息，并支持排序和筛选。 +- **容器组**：以最细粒度监控容器（Pod）的状态和资源消耗。 + +### 资源 + +查看和管理 Kubernetes 系统资源： + +- **网络**：监控系统中实施的网络安全策略以及每个命名空间的网络连接性。 +- **CRDs**：管理系统中的各种自定义资源声明。 + +### 中间件 + +查看 Olares 中各种中间件服务的使用情况。 \ No newline at end of file diff --git a/docs/zh/manual/olares/controlhub/navigate-control-hub.md b/docs/zh/manual/olares/controlhub/navigate-control-hub.md new file mode 100644 index 000000000..599f9c455 --- /dev/null +++ b/docs/zh/manual/olares/controlhub/navigate-control-hub.md @@ -0,0 +1,201 @@ +--- +outline: [2, 3] +description: 了解控制面板中的应用、资源、网络配置与中间件服务的。 +--- + +# 了解 Control Hub 界面 + +本wen将带你逐一了解 Control Hub 中的各个功能模块及其使用方法。 + +## 浏览 + +**浏览** 部分将资源组织为两类命名空间： + +- 用户项目：包括每个 Olares 用户的独立命名空间。 + - `user-space-*`：用户内置应用。 + - `user-system-*`：与用户相关的系统程序，包括 Olares 应用运行时组件、调度程序和跨应用交互代理。 +- 系统项目：包括 Olares 集群的核心应用以及系统级服务程序。 + +:::info 提示 +Olares 成员仅能访问自己的命名空间，而 Olares 管理员可以访问所有用户和系统命名空间。 +::: + +在第二列中，你可以查看命名空间内的所有资源类型。 + +### 工作负载 + +在 Olares 中，工作负载表示运行在集群上的应用，主要对应 Kubernetes 的三种资源类型： + +- **部署**（Deployment） + - Kubernetes 中最常见的工作负载类型。 + - 自动生成 `ReplicaSet` 调度并创建 Pod，实现水平扩展。 + +- **有状态副本集**（StatefulSet） + - 部署有状态的 Pod，例如数据库、分布式文件存储或内存缓存的 Pod。 + - 每个 Pod 的状态可能不同，通常按顺序调度。 + +- **守护进程集**（DaemonSet） + - 在每个节点上调度并运行一个 Pod。生成的 Pod 数通常等于节点数。 + - 用于节点特定的硬件操作。 + +### 工作负载详情 + +![alt text](/images/how-to/olares/controlhub/browse/02.jpg#bordered) + +工作负载资源的信息包括： + +- **详情**：资源的基本信息。 +- **容器组**：Pod 的基本信息。 +- **端口**：工作负载 Pod 容器暴露的所有端口集合。 +- **环境变量**：在 Pod 模板中为工作负载定义的环境变量。 +- **标签**：配置在 `workload` 元数据中，用于控制器管理协调和资源筛选。 +- **注解**：功能类似于标签，但更灵活，用于控制器管理工作负载。 +- **事件**：最近一小时内与工作负载相关的事件日志，通常显示 Pod 调度状态。 + +### 容器详情 + +Pod 的信息包括： + +- **信息**：容器的基本信息。 +- **容器**：容器的容器列表。 +- **卷**：为容器配置的持久卷。 +- **环境变量**：为容器定义的环境变量。 +- **事件**：按时间顺序记录与容器相关的事件。 + +![containers](/images/how-to/olares/controlhub/browse/04.jpg#bordered) + +### 保密字典 + +保密字典（Secrets）用于存储密码、凭据和关键配置等敏感数据。在 Kubernetes 中，这些数据默认以 Base64 编码。 + +![secrets](/images/how-to/olares/controlhub/browse/11.jpg#bordered) + +展开**保密字典**可查看应用命名空间下的所有密文数据。 + +信息包括： + +- **信息**：Secret 的基本信息，例如所属命名空间和创建时间。 +- **数据**：Secret 的**数据键**和**数据值**。 + +:::tip 提示 +**数据值**默认以 `Base64` 显示，可点击右上角的 **visibility预览**按钮查看原文。 +::: + +### 配置字典 + +配置字典（ConfigMap）结构类似于**保密字典**，但内容以明文保存。 + +![configmaps](/images/how-to/olares/controlhub/browse/12.jpg#bordered) + +展开**配置字典**可查看应用命名空间下的所有配置。 + +信息包括： + +- **信息**：配置字典的基本信息，如命名空间和创建时间。 +- **数据**：配置字典的**数据键**和**数据值**。 + +### 服务账户 + +**服务账户**（Service accounts）是 Kubernetes 的一种机制，用于验证集群容器应用并允许其访问 Kubernetes 管理的集群资源。 + +![Service accounts](/images/how-to/olares/controlhub/browse/13.jpg#bordered) + +展开 **服务账户** 部分可查看应用命名空间下的所有服务账户。 + +信息包括： + +- **信息**：服务账户的基本信息，如命名空间、创建时间等。 +- **数据**：与服务账户关联的 **Secret** 的**数据键**和**数据值**。 +- **Kubeconfig 设置**：服务账户自动生成的 Kubeconfig 配置，可下载用于应用或直接读取 `/var/run/secrets/kubernetes.io/serviceaccount/` 中的配置。 + +### 服务 + +**服务**（Service）通过网络服务将运行在单个或一组 Pods 上的应用暴露出来，并根据定义的选择器分发流量。 + +![service1](/images/how-to/olares/controlhub/browse/14.jpg#bordered) + +服务的信息包括： + +- **属性**：服务的基本信息，如命名空间、创建时间、选择器、虚拟 IP 等。 +- **工作负载**：选择器选择的所有工作负载。 +- **端口**：暴露的所有端口信息。 +- **容器组**：服务选择的所有 Pods 及其状态。 +- **标签**：服务的标签。 +- **注解**：服务的注解。 +- **事件**：与服务相关的事件。 + +## 命名空间 + +**命名空间** 提供基于用户的资源消耗和工作负载状态视图。 + +![namespace](/images/how-to/olares/controlhub/namespace/01.jpg#bordered) + +### 用量排名 + +按命名空间组织系统资源消耗。 + +![namespace list](/images/how-to/olares/controlhub/namespace/02.jpg#bordered) + +信息包括： + +- **配额**：此命名空间的系统资源使用百分比。 +- **绒球**：按资源消耗排序的所有 Pods，可通过关键字搜索。 + +### 资源 + +显示当前和历史资源利用率图表，可按用户筛选查看。 + +![resources](/images/how-to/olares/controlhub/namespace/04.jpg#bordered) + +## 容器组 + +**容器组**提供全面的容器状态和资源使用视图。 + +信息包括： + +- **Pod 列表**：Olares 中的所有 Pods。 +- **资源**：显示容器的物理资源消耗。 + +![resources](/images/how-to/olares/controlhub/pods/04.jpg#bordered) + +## 资源 + +包括软件和硬件相关资源。 + +### 网络 + +**网络策略**（Network policies）定义网络连接规则，基于命名空间的沙盒机制提供隔离。 + +#### 入站规则 + +显示允许进入命名空间的入站流量的规则列表。 + +#### 出站规则 + +显示允许离开命名空间的出站流量的规则列表。 + +### CRDs + +列出 Olares 中所有基于 Kubernetes 的自定义资源声明。 + +![CRDs](/images/how-to/olares/controlhub/resources/02.jpg#bordered) + +信息包括： + +- **信息**：显示 CRD 的名称、组、作用域和创建时间。 +- **自定义资源**：此 CRD 下的所有自定义资源。 + +## 中间件 + +管理员可在此管理中间件。 + +:::tip 提示 +仅管理员可访问**中间件**页面。 +::: + +信息包括： + +- **信息**：集群数据，如名称、命名空间、访问地址等。 +- **数据库**：各应用使用的数据库概览。 + +![postgres](/images/how-to/olares/controlhub/middleware/01.jpg#bordered) \ No newline at end of file diff --git a/docs/zh/manual/olares/controlhub/view-container.md b/docs/zh/manual/olares/controlhub/view-container.md new file mode 100644 index 000000000..6f50cbfbb --- /dev/null +++ b/docs/zh/manual/olares/controlhub/view-container.md @@ -0,0 +1,43 @@ +--- +description: Troubleshooting application issues status by examining the container staus or exporting logs +--- +# 检查容器状态 + +Pods 页面提供了 Olares 环境中所有 Pod 的全面视图，允许你在 Kubernetes 提供的最小粒度上进行管理。 + +本文档介绍如何查看容器状态，并导出容器日志。 + +## 查看容器状态 + +点击列表中的 Pod 可进入其详情页，你可以： + +- 查看容器日志。 +- 访问容器环境。 +- 查看容器端口和环境变量。 +- 在只读模式下查看 Pod 的 YAML 配置。 + + :::tip 提示 + 无法从该视图直接编辑 YAML 配置。YAML 配置由 Olares 通过应用负载模板和 Webhook 管理。 + ::: + +![Pod 详情](/images/how-to/olares/controlhub/pods/02.jpg#bordered) + +## 导出容器日志以诊断故障 + +为了有效诊断和解决问题，你可能需要检查容器的详细日志： + +![Log 操作](/images/manual/olares/controlhub-log.png) + +1. 在浏览列中，导航到你的应用，然后依次进入**部署** > **容器**。 +2. 找到状态异常的容器（带有橙色状态下标）。 +3. 点击容器旁边的 article 按钮。 +4. 在弹出的日志窗口中，选择以下操作来管理日志： + - 点击 download_2 按钮下载完整的日志文件。 + - 点击 autorenew 按钮刷新并查看最新的日志条目。 + - 点击 play_pause 按钮开始或暂停日志的实时更新。 + + + + + + diff --git a/docs/zh/manual/olares/controlhub/view-database-status.md b/docs/zh/manual/olares/controlhub/view-database-status.md new file mode 100644 index 000000000..1f3bc89e5 --- /dev/null +++ b/docs/zh/manual/olares/controlhub/view-database-status.md @@ -0,0 +1,57 @@ +--- +description: 在 Olares 中使用 Bytebase 查看数据库状态。学习添加和管理 PostgreSQL、MongoDB 实例，使用 SQL 编辑器操作数据库。 +--- +# 在 Olares 中查看数据库状态 + +你可以使用第三方数据库中间件应用在 Olares 中查看数据库状态。本指南以 Bytebase 为例，演示如何通过中间件访问数据库。 + +## 准备工作 + +确保你已从**应用市场**安装 Bytebase。 + +![安装bytebase](/images/how-to/olares/controlhub/middleware/07.jpg#bordered) + +## 添加 PostgreSQL 实例 + +在 Bytebase 中添加 PostgreSQL 实例： + +1. 在 **Bytebase** 中，点击**添加实例**，选择 **PostgreSQL**。 +2. 配置实例： + - **实例名称**：输入 `Olares` 或其他名称。 + - **环境**：选择 `PROD` 或 `TEST`。 + - **主机**、**用户名**、**密码**：根据**控制面板**的**中间件**部分中的信息填写。 + + ![配置PostgreSQL](/images/how-to/olares/controlhub/middleware/09.jpg#bordered) + +3. 点击**创建**保存更改并连接实例。 + +现在，你应该能够查看刚刚添加的 PostgreSQL 实例的详细信息。 + +![PostgreSQL信息](/images/how-to/olares/controlhub/middleware/10.jpg#bordered) + +## 添加 MongoDB 实例 + +在 Bytebase 中添加 MongoDB 实例： + +1. 在 **Bytebase** 中，点击**添加实例**，选择 **MongoDB**。 +2. 配置实例： + - **实例名称**：输入 `Olares` 或其他名称。 + :::info 提示 + 请勿使用重复的实例名称。 + ::: + - **环境**：选择 `PROD` 或 `TEST`。 + - **主机**、**用户名**、**密码**：根据 Control Hub 的 **中间件** 部分中的信息填写。 + + ![配置MongoDB](/images/how-to/olares/controlhub/middleware/11.jpg#bordered) + +3. 点击**创建**保存并连接实例。 + +现在，你应该能够查看刚刚添加的 MongoDB 实例的详细信息。 + +![MongoDB 信息](/images/how-to/olares/controlhub/middleware/12.jpg#bordered) + +## 编辑数据库 + +在 Bytebase 中，点击右上角的 **SQL 编辑器**，进入**编辑器**页面以进行进一步操作。 + +![编辑数据库](/images/how-to/olares/controlhub/middleware/13.jpg#bordered) \ No newline at end of file diff --git a/docs/zh/manual/olares/desktop.md b/docs/zh/manual/olares/desktop.md new file mode 100644 index 000000000..316e284ff --- /dev/null +++ b/docs/zh/manual/olares/desktop.md @@ -0,0 +1,74 @@ +--- +description: 了解 Olares 桌面的基本概念与操作方式，包括如何使用 Dock、启动器、窗口控制与全局搜索，帮助你高效管理系统与应用。 +--- + +# 了解桌面 + +桌面应用是用户与 Olares 系统交互的主要入口。它提供直观高效的方式来管理和使用系统内置应用以及用户安装的应用。 + +## 桌面基础概念 +![桌面](/images/zh/manual/olares/desktop.png) + +### Dock 与启动台 + +- **Dock（应用坞）：** 屏幕侧边的快速启动栏，用于固定常用应用。 +- **启动台（Launchpad）：** 点击 Dock 中的启动台图标可打开，展示所有已安装应用。 + +### 应用窗口 + +- 应用默认以窗口模式打开。 +- 支持以下窗口操作： + - 拖动标题栏移动窗口 + - 拖动边缘调整大小 + - 最小化、最大化或关闭窗口 +- **搜索功能：** 快速启动应用、查找文件等。 + +## 使用启动台 + +通过启动台，你可以： + +- 查看所有已安装应用 +- 点击图标打开对应应用 +- 拖动图标调整在启动台中的顺序 +- 拖动图标到 Dock，固定为常用应用 + +### 卸载应用 + +1. 长按应用图标进入编辑模式。 +2. 若图标右上角出现 **X**，点击即可卸载该应用。 + +::: tip 注意 +系统内置应用（如文件管理器、应用市场、个人主页）无法卸载。 +::: + +## 管理应用窗口 + +应用默认以窗口模式打开，即以嵌入桌面的 iframe 页面形式展示。你可以像使用传统桌面系统一样操作窗口： + +- 拖动标题栏移动窗口 +- 拖动边缘调整窗口大小 +- 最小化、最大化或关闭窗口 +- 点击open_in_new按钮，在新浏览器标签页中打开应用 + +::: tip 提示 +部分应用仅支持标签页视图打开。 +::: + +## 使用全局搜索 + +你可以通过以下任一方式唤出 Olares 的全局搜索： + +- 按下快捷键 `Shift + Space` +- 点击 Dock 中的「搜索」图标 + +| 搜索对象 | 支持的操作 | +| :---------------------------------- |:--------------------| +| 已安装的应用 | 直接打开应用 | +| 文件管理器中的文档目录 | 支持按文件名或全文内容搜索 | +| 文件管理器中的其他目录 | 仅支持按文件名搜索 | +| 文件管理器中的同步磁盘 | 仅支持按文件名搜索 | +| Wise 阅读器内容 | 支持 RSS、网页、PDF 的全文搜索 | +| **更多内容** | | +| 设置 | 调整 Olares 外观设置 | +| 应用管理 | 安装、卸载或更新应用 | + \ No newline at end of file diff --git a/docs/zh/manual/olares/files/add-edit-download.md b/docs/zh/manual/olares/files/add-edit-download.md new file mode 100644 index 000000000..8ecfaa58c --- /dev/null +++ b/docs/zh/manual/olares/files/add-edit-download.md @@ -0,0 +1,114 @@ +--- +description: 在 Olares 中执行基础文件操作，包括添加、编辑和下载文件的具体步骤。 +--- +# 添加、编辑和下载 +**文件管理器**使用方式与其他同类软件类似。本文将介绍一些常用操作，帮助你快速上手。 + +## 上传文件 + +### 通过 Files 应用上传 +1. 打开**文件管理器**。 +2. 在左侧边栏中选择要上传文件的目录，例如"文档"。 +3. 使用以下任一方法上传多个文件或文件夹： + - 将文件从本地文件管理器拖放到文件窗口中。 + - 右上角点击 **drive_folder_upload上传**。 + - 在空白区域右键单击，在上下文菜单中选择**上传文件**或**上传文件夹**。 + +:::tip +文件支持断点续传。如果上传被中断，将自动从上次检查点继续上传。 +::: + +### 通过 LarePass 桌面端上传 +:::info 导入 Olares ID +使用 LarePass 桌面端前，需要先通过助记词导入 Olares ID。请确保已经[备份好助记词](../../larepass/back-up-mnemonics.md)。 +::: +LarePass 桌面端的文件上传操作与 Files 应用类似，上传的文件会自动与你的 Olares ID 同步。 + +### 通过 LarePass 移动端上传 +你也可以通过 LarePass 移动应用在手机上上传文件或文件夹。 + + + + + + +通过 LarePass 移动应用上传的文件也会自动与你的 Olares ID 同步。 +## 下载文件 +下载多个文件时，文件管理器网页版和 LarePass 桌面端的行为有所不同： +* **文件管理器网页版**：下载任务由你的浏览器管理，可使用浏览器下载功能管理下载队列，可暂停、恢复或取消任务。 +* **LarePass 桌面端**：支持在 LarePass 里管理下载队列，可暂停、恢复或取消任务，方便查找已下载文件。 + +:::tip 提示 +* 文件夹下载仅在 LarePass 桌面版支持。 +* 如需下载大文件或批量下载文件，建议使用 LarePass 桌面端，可获得更强大的下载管理功能和更好的使用体验。详情请访问[官方页面](https://olares.cn/larepass)了解和下载。 +::: + +1. 打开**文件管理器**。 +2. 选中任意文件，右键打开上下文菜单，选择**下载**。 +3. 在弹窗中选择保存位置。 + +## 预览和编辑文件 +双击文件即可打开预览。**文件管理器**支持预览以下格式： + +* **图片**：JPG、JPEG、PNG、BMP、WEBP、SVG +* **视频**：MP4、MKV、AVI、MOV、MPEG、MTS、TS、WMV、WEBM、RM、3GP +* **音频**：MP3、WMA、WAV、OGG、AAC、M4A、APE、FLAC +* **文本**：PDF、TXT、JS、CSS、XML、YAML、HTML + +**文件管理器**还支持编辑以下文本格式：TXT、JS、CSS、XML、YAML、HTML。 + +![预览](/images/manual/olares/files-preview.png#bordered) +## 搜索文件 +通过桌面搜索功能，可以轻松找到**文件管理器**中的文件。 +:::tip 提示 +**存储盘**（Drive）中的 `/Documents/` 目录支持全文搜索，可搜索文件内容。其他目录则可通过文件名搜索。 +::: +1. 点击 Dock 中的search图标打开搜索窗口。 +2. 在搜索框中输入要查找的文件相关关键词。 +3. 使用方向键arrow_upwardarrow_downward选择搜索范围：**存储盘**或**同步盘**，按 **Enter** 查看搜索结果。 + +![搜索](/images/manual/olares/files-search.png#bordered){width="90%""} +## 删除文件 +:::warning 警告 +删除的文件无法恢复。 +::: +1. 打开**文件管理器**。 +2. 选中要删除的文件，可通过以下方式操作： + - 右键点击，从上下文菜单中选择**删除** + - 右上角点击 **more_horiz更多**，选择**删除** +3. 在弹窗中确认删除。 + +## 切换显示视图 + +可在列表视图和网格视图之间切换，以不同方式显示文件和文件夹。 + +![显示视图](/images/manual/olares/files-display-view.png) +## 快捷键 +选择多个文件： + +* **Windows**：按住 **Control** 选择目标文件 +* **Mac**：按住 **Command** 选择点击目标文件 \ No newline at end of file diff --git a/docs/zh/manual/olares/files/index.md b/docs/zh/manual/olares/files/index.md new file mode 100644 index 000000000..4b18fbcb5 --- /dev/null +++ b/docs/zh/manual/olares/files/index.md @@ -0,0 +1,50 @@ +--- +description: 使用 Olares 文件管理器进行文件存储、同步和访问，实现高效的文件管理和团队协作。 +--- +# 管理文件 + +Olares 内置的文件应用为用户提供了安全高效的文件存储与同步解决方案，支持从任何设备或浏览器访问各种文件类型。主要优势包括： + +* **随时随地访问**：使用任意设备端的浏览器，从任何位置查看、下载或共享存储在 Olares 中的文件。 +* **无缝同步**：确保数据在所有设备间保持最新。 +* **集中存储**：简化信息检索与集成，无论是个人文档还是团队共享资料，均可轻松访问、管理与更新。 + +## 界面概览 + +文件管理器的界面类似于 Windows 资源管理器或 macOS 的访达，允许你整理和访问文档、图片、视频或其他文件。主要由以下三个部分组成： + + +![Files](/images/zh/manual/olares/files.png#bordered) + +* **存储盘**（Drive）：用于存储不需要频繁同步或修改的文件。 +* **同步盘**（Sync）：用于在设备间同步文件和目录。 +* **应用盘**（Application）：存储应用与缓存数据，仅用于开发和调试目的。 +* **云存储** （Cloud Drive）：用于加载、访问第三方云存储服务包括 Google Drive、Drop Box、 AWS S3、腾讯云对象存储服务（COS）。 + +--- +
+

添加、编辑和下载文件

+了解 Olares 中文件管理的基本操作。 +
+ +
+

同步和共享文件

+了解如何在设备间保持文件更新，以及如何与其他 Olares 成员共享文件。 +
+ +
+

挂载 SMB

+ 了解如何在 Olares 中挂载并访问 NAS 设备或网络服务器上的 SMB 共享文件夹。 +
+ +
+

挂载云存储

+ 了解如何在 Olares 中挂载并访问第三方云存储服务。 +
+ + + + + + + diff --git a/docs/zh/manual/olares/files/mount-SMB.md b/docs/zh/manual/olares/files/mount-SMB.md new file mode 100644 index 000000000..154842cfb --- /dev/null +++ b/docs/zh/manual/olares/files/mount-SMB.md @@ -0,0 +1,31 @@ +--- +description: 了解如何在 Olares 中挂载和访问来自 NAS 设备或网络服务器的 SMB 共享文件夹。包含连接 SMB 共享和管理网络文件的详细步骤说明。 +--- +# 挂载 SMB 共享 +SMB（Server Message Block，服务器消息块）是一种用于在网络上共享文件、打印机和其他资源的协议。如果你的局域网中有 NAS 设备或其他 SMB 服务器，可以轻松地将 SMB 共享挂载到 Olares 中来访问和管理共享文件。 + +## 准备工作 +- Olares 与 SMB 服务器（如 NAS 设备）必须处于同一局域网中。 +- 已经获取以下 SMB 共享信息： + - **SMB 共享路径**：通常格式为 `\\\<共享文件夹名>`。 + - **用户名和密码**：用于访问 SMB 共享的登录凭据。 + +## 将 SMB 共享文件夹挂载到 Olares +1. 打开**文件管理器**，进入**存储** > **外部存储**。 +2. 点击右上角的**连接服务器**。 +3. 在**服务器地址**栏中输入 SMB 共享路径（例如：`\\192.168.1.100\Documents`），然后点击**确定**。 + :::tip 保存常用服务器地址 + - 输入共享路径后，点击 add 可将服务器地址添加到**常用服务器**。 + - 要删除已保存的服务器，点击**常用服务器**下的服务器路径，然后点击 remove。 + ::: + ![添加 SMB 共享路径](/images/manual/olares/add-SMB-share-path.png#bordered) +4. 输入**用户名**和**密码**，然后点击**确定**。 + +连接成功后，SMB 共享将显示在**外部存储**目录中，你就可以方便地访问共享文件和文件夹了。 + +## 卸载 SMB 共享 +要卸载 SMB 共享： +1. 打开**文件管理器**，进入**存储** > **外部存储**。 +2. 右键选择已挂载的 SMB 共享文件夹，从上下文菜单中选择**卸载**。 + +完成后，Olares 将与 SMB 文件夹安全断开连接。 \ No newline at end of file diff --git a/docs/zh/manual/olares/files/mount-cloud-storage.md b/docs/zh/manual/olares/files/mount-cloud-storage.md new file mode 100644 index 000000000..c6c4ba85c --- /dev/null +++ b/docs/zh/manual/olares/files/mount-cloud-storage.md @@ -0,0 +1,36 @@ +--- +description: 了解如何在 Olares 中挂载并访问各类云存储服务。 +--- + +# 挂载与使用云存储 + +你可以通过 Olares 的**集成**功能轻松挂载云存储服务，并在**文件管理器**应用中直接访问和管理云端文件。 + +![云存储](/images/zh/manual/olares/files-cloud.png) + +## 挂载云存储 + +要挂载云存储，请在 **LarePass** 或 Olares 的**设置**中连接对应服务： + +- **基于 OAuth 的存储服务**：如 Google Drive 和 Dropbox。通过 [LarePass 手机端](../../larepass/integrations.md#通过-oauth-添加云盘)添加对应的集成。 +- **基于 API 凭证的存储服务**：如 AWS S3 或腾讯云对象存储（COS）。可通过 [LarePass 手机端](../../larepass/integrations.md#通过-api-密钥添加云盘)或 [Olares 设置](../settings/integrations.md#通过-api-密钥添加云对象存储)中添加对应的集成。 + +连接成功后，云存储将自动挂载至**文件管理器**应用中的**云存储**目录下。 + +## 访问云存储 + +挂载后，你可以像使用本地存储一样访问和管理云端文件： + +- **上传 / 下载**文件 +- **预览**支持的文件类型 +- **重命名**、**移动**或**删除**文件和文件夹 + +你在文件管理器中的操作将自动同步至对应的云存储服务。 + +## 卸载云存储 + +若需取消挂载，可移除对应的集成服务： + +- [在 LarePass 中移除集成](../../larepass/integrations.md#断开集成) +- [在 Olares 设置中移除集成](../settings/integrations.md#查看与管理现有集成) + diff --git a/docs/zh/manual/olares/index.md b/docs/zh/manual/olares/index.md new file mode 100644 index 000000000..ad9e00fac --- /dev/null +++ b/docs/zh/manual/olares/index.md @@ -0,0 +1,22 @@ +--- +description: 通过 Olares 系统应用文档了解如何使用 Olares，包括个性化设置、应用管理、文件处理、安全配置和团队协作功能。 +--- + +# Olares 系统应用文档 +Olares 系统应用是 Olares 生态的核心组成部分，它们预装在你的 Olares 系统中，旨在提供一套基础且强大的工具集，帮助你高效地管理文件、应用、设置系统，管理知识、以及完成更多日常任务。理解这些系统应用的功能和价值，将使你能够充分利用 Olares 的潜力，打造一个符合你个人需求的工作和生活环境。 + +本文档将帮助你全面掌握 Olares 系统应用的使用方法，打造一个符合个人工作和生活需求的个人云环境。 + +## 系统应用能做什么？ + +探索以下指南，充分发挥 Olares 内置应用的价值： + +- **[导航并自定义桌面](./desktop.md)**：启动应用、整理工作区并在 Olares 中全局搜索。 +- **[安装和管理应用](./market.md)**：在开放、无许可的应用商店中发现、安装、更新或移除应用及推荐算法。 +- **[存储、同步与访问文件](./files/)**：在集中式存储中安全上传、下载、组织与共享文件，并实现实时同步。 +- **[使用 Vault 管理密码](./vault/)**：安全存储凭据、管理数字身份并生成一次性验证码。 +- **[使用 Wise 收集与整理知识](./wise/)**：从多平台收集、消费并管理内容，获取个性化推荐，构建个人信息中心。 +- **[使用设置配置系统](./settings/)**：在单一界面完成用户、应用、网络、集成、安全、外观、备份等设置。 +- **[通过控制面板监控、管理应用](./controlhub/)**：在单一控制台监控系统状态、管理应用服务并优化 Olares 环境。 +- **[通过仪表盘了解系统状态](./resources-usage.md)**：以直观界面查看实时资源使用和性能指标。 +- **[设计专属 Olares 个人主页](profile.md)**：定制个人主页，展示身份并与他人分享。 diff --git a/docs/zh/manual/olares/market.md b/docs/zh/manual/olares/market.md new file mode 100644 index 000000000..ee0b7d5bb --- /dev/null +++ b/docs/zh/manual/olares/market.md @@ -0,0 +1,106 @@ +--- +outline: [2, 3] +description: 通过 Olares 应用市场发现和管理应用，掌握安装更新和卸载方法，了解集群应用和自定义应用的部署流程。 +--- + +# 安装、卸载和更新 + +本文档介绍如何安装、更新和卸载应用，以及如何安装自定义应用。 + +## 开始之前 + +在开始之前，建议你先熟悉一些与 Olares 应用相关的概念： + +| 术语 | 描述 | +|-----------------------------------------|--------------------------------------------------------------| +| [系统应用](../concepts/application.md#系统应用) | Olares 内置的预安装应用，例如 Profile、文件管理器和 Vault。 | +| [社区应用](../concepts/application.md#社区应用) | 由第三方开发者创建和维护的应用。 | +| [共享应用](../concepts/application.md#共享应用) | 一种特殊类型的社区应用，向集群范围的授权应用共享服务和资源。 | +| [授权应用](../concepts/application.md#授权应用) | 被授权访问共享应用的一类应用。 | +| [依赖项](../concepts/application.md#依赖项) | 应用需要先安装的前置应用。 | + +## 查找应用 + +Olares **应用市场**提供多种方式发现和浏览应用： + +在**发现**页面： +* **精选应用**：由编辑团队策划，展示流行和季节相关的应用。 +* **社区推荐**：最受 Olares 社区喜爱的推荐应用。 +* **热门应用**：使用率和下载量最高的应用。 +* **最新应用**：最近添加到市场的应用。 + +你还可以根据功能浏览应用： +* **效率**：适用于工作场景和提升效率的应用。 +* **工具**：解决特定问题或完成任务的工具。 +* **娱乐**：用于休闲娱乐的应用。 +* **社交网络**：连接他人的平台。 +* **推荐**：用于 Wise 的去中心化内容推荐算法。 + +:::tip 提示 +有关在 Wise 中使用推荐功能的信息，请参阅[发现主题内容](wise/recommend.md)。 +::: + +![市场](/images/manual/olares/market-discover.png#bordered) + +## 安装应用 + +1. 打开**应用市场**，找到所需应用，点击**获取**。 +2. 当操作按钮变为“**安装**”时，点击以开始安装。 +3. 安装完成后，按钮将变为“**打开**”。 + +:::tip +若要取消安装，在操作按钮上悬停，点击**取消**。 +::: + +### 安装共享应用和授权应用 + +为确保共享服务在集群内正常运行和可访问，请根据共享应用的类型采取相应的安装流程： + +* **无界面的后端服务应用**： + 此类共享应用通常需要通过其他授权应用为用户提供使用入口，以 Ollama 为例： + 1. 管理员先安装 Ollama。安装后，共享服务在集群内可用。 + 2. 集群成员（包括管理员）安装相应的授权应用以访问共享服务，如，Open WebUI 或 LobeChat。 + +* **自带用户界面的完整应用**： + 此类应用可独立为用户提供服务，如 Dify 共享版、ComfyUI 共享版等。 + + 1. 管理员首先安装共享应用。此步会启用集群的共享服务，同时也安装一个同名客户端界面作为访问入口。 + ::: tip ComfyUI 启动器 + ComfyUI 共享版包含一个桌面启动器组件，用于管理 ComfyUI 服务和相关资源。管理员需要从 ComfyUI 启动器里配置并启用服务。 + ::: + 2. 集群中的其他成员安装相同的共享版应用。对于这些用户，安装的仅是一个服务访问入口。 + +### 安装自定义应用 + +1. 准备 Olares 应用 Chart 文件（格式为 `.zip`、`.tgz`、`.tar` 或 `.gz`）。 +2. 打开**应用市场**，点击**我的 Olares** > **自定义**查看所有自定义应用。 +3. 点击**上传自定义 Chart**并选择文件。 + +## 更新应用 + +1. 打开**应用市场**，在左侧边栏**我的 Olares** 旁查看更新通知（如果有更新可用，将显示标记数字）。 +2. 点击**我的 Olares** > **可用更新**查看所有可更新应用。 +3. 点击**全部更新**以一次性更新所有应用，或单独更新每个应用。 + +## 卸载应用 + +### 从应用市场卸载 + +1. 打开**应用市场**，点击左侧边栏的**我的 Olares** 查看所有已安装应用。 +2. 点击应用操作按钮旁的 keyboard_arrow_down，选择**卸载**。 + +### 从启动台卸载 + +1. 在 Olares 中，点击 Dock 中的启动台图标，显示所有已安装应用。 +2. 点击并按住应用图标，直到所有应用开始抖动。 +3. 点击应用图标上的 cancel 卸载。 + +## 常见问题 + +### 为什么我无法安装应用？ + +如果无法安装应用，可能是由于以下原因： +* **系统资源不足**：尝试释放系统资源，或增加资源配额。 +* **缺少依赖项**：在应用详情页在检查是否已安装所需依赖项。 +* **系统版本不兼容**：尝试将 Olares 升级到最新版本。 +* **共享应用限制**（对于 Olares 成员）：安装授权应用，并联系你的 Olares 管理员安装相应的共享应用。 \ No newline at end of file diff --git a/docs/zh/manual/olares/nft-image.md b/docs/zh/manual/olares/nft-image.md new file mode 100644 index 000000000..c666ce6df --- /dev/null +++ b/docs/zh/manual/olares/nft-image.md @@ -0,0 +1,50 @@ +--- +description: 在 Olares 中导入区块链钱包、关联 NFT 藏品并设置为个性化头像，展现独特的数字身份标识。 +--- +# 使用 NFT 图像作为个人头像 + +Olares 支持使用 NFT（非同质化代币）图像作为你的个人头像，为你的数字身份增添个性化色彩。此功能需要将区块链钱包连接到你的账户。 + +## 开始之前 + +在开始之前，请先[将 Olares 与 Olares Space 集成](settings/integrations.md)。 + +## 第一步：设置区块链钱包 + +1. 在 Chrome 应用店找到并安装 MetaMask 扩展程序。 +2. 创建一个新钱包或导入现有钱包。 +3. 按界面提示完成 MetaMask 钱包的设置。 + +## 第二步：导入区块链钱包 + +1. 打开**设置**，在左侧边栏选择**集成**。 +2. 点击右侧的 Olares Space 卡片。 +3. 点击**导入**，并按照屏幕提示连接你的 MetaMask 钱包。 + +导入钱包后，页面会刷新并显示钱包详情。 + +## 第三步：关联 Olares ID + +1. 点击**绑定**，并在 MetaMask 中确认此操作。 + 此操作还会触发 LarePass 应用中的确认提示。 +2. 打开 LarePass 应用。你应该会看到确认提示。如果没有： + + a. 前往**设置** > **集成**。 + + b. 点击 Olares Space 卡片。 + + c. 在确认提示中，点击**确认**授权。 + +3. 返回 Olares，点击**确认**完成与 Olares ID 的关联。 + +完成后，你可以在 Olares 中访问你的 NFT 收藏。 + +## 第四步：选择 NFT 作为个人头像 + +将你喜欢的 NFT 图像设置为唯一头像： + +1. 打开 **Profile**。 +2. 在**头部**选项卡下，点击头像图片。 +3. 在对话框中，点击 **NFT 头像**。 +4. 从你的 NFT 收藏中选择一张图片。 +5. 点击**创建**应用更改。 \ No newline at end of file diff --git a/docs/zh/manual/olares/profile.md b/docs/zh/manual/olares/profile.md new file mode 100644 index 000000000..95a655897 --- /dev/null +++ b/docs/zh/manual/olares/profile.md @@ -0,0 +1,38 @@ +--- +outline: [2, 3] +description: 创建独特的 Olares 个人主页，设计个性化封面、添加社交媒体链接、选择布局风格，并通过访问数据分析优化展示效果。 +--- + +# 设计你的 Olares 个人主页 + +你可以创建一个独特的个人主页，展示你的数字身份。 + +![Profile](/images/manual/olares/profile.png) + +## 访问你的主页 + +你的个人主页默认 URL 为 `{本地名称}.olares.cn`。 + +## 自定义你的主页 + +![Profile](/images/zh/manual/tasks/profile-example.png#bordered) + +### 设计封面 + +打造符合你风格的主页头部。你可以像拼积木一样，使用文本、图片和链接等多种元素构建内容。 + +### 添加社交媒体链接 + +通过添加社交媒体链接来增加曝光。访问者可以通过点击主页上的相应图标轻松访问你的社交媒体资料。 + +### 选择布局 + +在外观设置中调整布局样式和背景方案，以优化主页的外观。 + +## 分享你的主页 + +你可以通过多种方式分享个人主页： + +* **通过社交平台分享**：直接将主页分享到热门社交媒体平台，例如 X、Meta 和 LinkedIn。 +* **通过二维码分享**：生成主页的二维码，下载并分享。 +* **作为数字名片分享**：创建一张包含主页 URL 的时尚数字名片，非常适合用于交流和拓展人脉。 \ No newline at end of file diff --git a/docs/zh/manual/olares/resources-usage.md b/docs/zh/manual/olares/resources-usage.md new file mode 100644 index 000000000..0d6fa58b1 --- /dev/null +++ b/docs/zh/manual/olares/resources-usage.md @@ -0,0 +1,95 @@ +--- +outline: [2, 3] +description: 通过 Olares 的仪表盘应用监控系统和应用状态。查看资源使用指标、应用性能数据，确保系统稳定运行。 +--- + +# 监控系统和应用状态 + +Olares 的**仪表盘**应用类似于 Windows 资源管理器，为你提供系统状态的集中视图，无需技术背景。从主面板中，你可以查看资源使用模式和详细的指标数据。 + +:::info +当你的 Olares 应用暴露在公网时，它们会因外部访问产生 FRP 流量成本。要监控这些成本和流量，请参阅[查看系统状态](../../space/manage-olares.md#查看系统状态)。 +::: + +## 访问监控仪表板 + +通过以下专业仪表板查看系统状态： + +- **概览**：显示当前资源使用情况和系统健康状态。 +- **应用**：显示运行中的应用及其状态。 + +## 概览 + +### 查看物理资源 + +在**概览**中直接监控以下四个核心指标： +- CPU 使用率 +- 内存使用量 +- 磁盘使用量 +- Pod 状态 + +![Dashboard overview](/images/manual/olares/dashboard-overview.png#bordered) + +### 查看详细指标 + +点击**详情**，查看过去 7 天的综合监控数据。 + +使用右上角的下拉菜单更改时间范围，或点击 refresh 更新监控数据。 + +以下指标帮助你保持系统的最佳性能： + +| 指标 | 描述 | 影响 | +|----------|---------------|--------------------| +| CPU 用量 | CPU 资源的使用百分比 | 持续高峰会导致系统变慢 | +| 内存用量 | 内存的使用百分比 | 影响应用性能和稳定性 | +| CPU 平均负载 | 活跃进程的平均数量 | 高负载表明系统过载 | +| 磁盘用量 | 磁盘空间的使用百分比 | 对数据可靠性至关重要，需防止过度使用 | +| Inode 用量 | Inode 的使用百分比 | 耗尽将阻止新文件的创建 | +| 磁盘吞吐 | 数据传输速率（MB/s） | 对大文件传输非常重要 | +| IOPS | 每秒输入/输出操作数 | 对小文件或随机数据访问至关重要 | +| 网络流量 | 网络使用情况（Mbps） | 反映网络速度和质量 | +| 容器组状态 | 按状态划分的 Pod 数量 | 反映应用的健康状态 | + +![Physical resource monitoring](/images/manual/olares/physical-resource-monitoring.png#bordered) + +### 查看资源配额 + +你可以查看 Olares 管理员分配的资源配额。 + +![Resource quota](/images/manual/olares/resource-quota.png#bordered) + +:::warning 警告 +当资源配额不足时，可能会出现以下问题： + +- 系统性能下降。 +- 无法安装新应用。 +- 资源密集型应用会自动暂停。 +::: + +### 追踪应用性能 + +**使用排名**面板显示 CPU 和内存资源消耗最高的前 5 个应用。要查看完整的应用资源使用列表，点击**更多**。 + +![Usage ranking](/images/manual/olares/usage-ranking.png#bordered) + +## 应用 + +**应用**仪表面板帮助你通过多种排序和筛选选项监控应用的资源使用模式。 + +使用右上角的下拉菜单，根据以下资源消耗指标排序应用： +- CPU 使用率 +- 内存使用率 +- 入站流量 +- 出站流量 + +![Applications](/images/manual/olares/applications.png#bordered) + +在升序和降序之间切换，找出资源消耗最高或最低的应用。 + +对于支持多入口的应用（如 WordPress），你可以点击图标切换不同入口类型，并查看其对应的资源指标。 +![Multiple entrances](/images/manual/olares/multiple-entrances.png){width=40%} + +:::tip 提示 +* 当应用列表较长时，可通过页面顶部的搜索框快速定位特定应用。 +* 定期检查资源消耗模式可帮助你识别可能需要优化或关注的应用。 +::: \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/backup.md b/docs/zh/manual/olares/settings/backup.md new file mode 100644 index 000000000..181c04b62 --- /dev/null +++ b/docs/zh/manual/olares/settings/backup.md @@ -0,0 +1,60 @@ +--- +description: 了解如何在 Olares 中创建、管理备份任务。本文档介绍文件与应用（如 Wise）的全量与增量备份，支持本地、外部和云存储方案。 +--- + +# 备份 Olares 数据 + +Olares 提供灵活的备份方案，可对**指定文件夹**与 **Wise 应用** 执行全量和增量备份，并支持设置自动备份计划，以确保您的数据安全。 + +## 添加备份任务 + +添加备份任务步骤如下： + +1. 进入**设置** › **备份**，点击**添加备份**。 +2. 选择**备份文件** 或**备份应用**。 +3. 在**添加备份任务**页面，配置备份基础信息如下： + + | 配置项 | 说明 | + |:-------------------------------|:-------------------------------------------------------------------------------------------------------------------------------------| + | **备份位置** | - **本地路径**：建议选择外接设备，例如 U 盘、SMB 网络目录或外部硬盘。
- **网络存储**：支持 Olares Space、AWS S3、腾讯云 COS。可通过**设置 ›
集成**添加账户，或在弹窗中点击**添加账户**直接添加。 | + | **Region**（仅限 Olares Space 存储） | 如果备份位置是 Olares Space，系统会自动选择对应的存储区域。 | + | **备份路径**（备份文件时显示） | 指定要备份的文件夹路径。 | + | **选择应用**（备份应用时显示） | 从下拉菜单中选择需要备份的应用，目前仅支持 Wise。 | + | **备份名称** | 输入便于识别的任务名称，建议包含用途及时间戳。 | + + + :::warning 注意 + 请在开始备份前确保以下事项： + + - 所选存储空间的可用容量足以存储该任务的备份数据。 + - 已成功订阅对应存储服务且账户处于正常状态。 + - 对目标存储路径拥有读写权限（例如挂载的 SMB 网络目录等）。 + ::: + +4. 设置备份计划与安全项目： + - **快照频率**：选择备份执行的频率，支持按**日/周/月**备份。 + - **快照时间**：指定具体运行时间。 + - **备份密码**：为备份文件加密，保护隐私。 +5. 点击 **提交**。系统首次将执行全量备份，后续按计划进行增量备份。 + + :::warning 注意 + 备份过程中请勿关闭主机或重启备份服务。 + ::: + +## 管理备份任务 + +创建成功后，备份任务将显示在备份首页。点击任务右侧 **>** 操作按钮可进入详情页进行管理： + +| 操作 | 说明 | +|:-------|:--------------------------------------------------------------------| +| **管理** | - **编辑**：修改快照频率与执行时间
- **暂停**：暂停执行备份任务
- **删除**：删除任务及其所有快照 | +| **立即快照** | 立刻手动执行一次备份 + +## 查看快照 + +在任务详情页底部，查看每次快照的**时间**与**状态**。点击右侧 **>** 操作按钮，可查看以下快照详情信息。 + +- **创建时间**：该快照的执行时间。 +- **大小**：快照占用空间大小。 +- **状态**：快照执行状态。 +- **备份类型**：显示该快照是全量备份还是增量备份。 \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/change-frp.md b/docs/zh/manual/olares/settings/change-frp.md new file mode 100644 index 000000000..7cf2c2c6d --- /dev/null +++ b/docs/zh/manual/olares/settings/change-frp.md @@ -0,0 +1,28 @@ +--- +description: 了解如何在 Olares 设置中更改反向代理选项，保证安全稳定的对外访问。 +--- + +# 更改反向代理选项 + +反向代理是一种安全网关，连接你的 Olares 与公共互联网。即便没有公网 IP，也可以通过反向代理将本地服务安全暴露到外网。 + +Olares 提供三种反向代理选项，适用于不同地区与网络环境： + +- **Cloudflare Tunnel** – 推荐全球用户使用。 + +- **Olares Tunnel** – 针对中国大陆用户优化，支持多地区 IDC 线路。 + +- **自建 FRP** – 适合拥有自有 FRP 服务器的用户。 + +## 如何更改反向代理选项 + +1. 打开设置，进入**系统** > **网络**页面。 + +2. 选择你想使用的反向代理方式。如果选择**自建 FRP**，需填写服务器地址、端口和认证方式。 + +3. 点击 **保存** 应用更改。 + +:::warning 更改请谨慎操作 +- Olares 会在安装过程中默认设置一种反向代理方式，修改该设置可能影响系统连通性，请谨慎操作。 +- Cloudflare Tunnel 与 Olares Tunnel 属于不同的网络服务，切换后将影响你所使用的流量套餐与功能权益。 + ::: diff --git a/docs/zh/manual/olares/settings/custom-app-domain.md b/docs/zh/manual/olares/settings/custom-app-domain.md new file mode 100644 index 000000000..f5dc8efdb --- /dev/null +++ b/docs/zh/manual/olares/settings/custom-app-domain.md @@ -0,0 +1,80 @@ +--- +outline: [2, 3] +description: 自定义 Olares 应用的访问地址，通过设置路由 ID 和域名，实现更简洁专业的应用访问方式。 +--- + +# 自定义应用 URL +无论是在本地还是远程，你都可以随时随地访问 Olares 应用。本文档将介绍如何为应用添加自定义域名。 + +## 开始之前 +在开始之前，建议你先熟悉一些与 Olares 应用相关的概念： + +- [端点 (Endpoints)](../../concepts/network.md#端点) +- [路由 ID (Route ID)](../../concepts/network.md#路由-id) + +## 为应用自定义域名 + +Olares 提供两种方法来优化应用的访问地址： +* 自定义路由 ID +* 自定义域名 + +### 自定义路由 ID +路由 ID 是访问 Olares 应用的重要组成部分，和 Olares 域名一起构成了你通过 Web 浏览器访问应用的 URL： + +`https://{routeID}.{OlaresDomainName}` + +为方便起见，Olares 为预安装的系统应用使用了易于记忆的路由 ID。对于社区应用，你可以通过更改路由 ID 快速获得一个简单易记的 URL。 + +以 Jellyfin 为例： + +1. 打开**设置**，在左侧边栏中选择**应用**。 +2. 点击右侧的 **Jellyfin** 查看应用详情。 +3. 前往**入口** > **设置端点**。可以看到 Jellyfin 的默认路由 ID，是一个数字和字母的组合 `7e89d2a1`。 +4. 在**设置自定义路由 ID** 旁，点击 **add** 打开设置对话框。 +5. 输入一个更易记的路由 ID，例如 `jellyfin`。 + + ![自定义路由 ID](/images/zh/manual/tasks/custom-route-id.png#bordered) +6. 点击**确认**。 + +现在，你可以通过新的 URL 访问 Jellyfin：`https://jellyfin.bob.olares.cn`。 + +### 自定义域名 + +除了使用默认的 Olares 域名，你还可以使用自己的域名访问应用，使其看起来更专业、更易记。 +:::info +仅认证级别为**内部**或**公开**的应用支持设置自定义三方域名。 +::: + + +:::info +- 中国大陆网络环境下，如果当前反向代理为 Olares Tunnel 或自建 FRP，配置三方域名时需要手动上传 HTTPS 证书及私钥。 +- 请确保你的自定义域名已完成备案，否则可能会影响正常访问。 +::: + +以 Affine 为例： + +1. 打开**设置**，在左侧边栏中选择 **应用**。 +2. 点击右侧的 **Affine** 查看应用详情。 +3. 前往**入口** > **设置端点**。 +4. 在**设置自定义域名**旁，点击 add 打开设置对话框。 + + ![设置三方域名](/images/zh/manual/tasks/set-custom-domain.png#bordered) +5. 输入你的自定义域名，例如 `hello.coffee`，并粘贴 HTTPS 证书及私钥，然后点击**确认**。 + + ![输入三方域名及证书](/images/zh/manual/tasks/enter-custom-domain.png#bordered){width=70%} +6. 点击**激活**，按提示在你的域名托管网站上添加 CNAME 记录，点击**确认**。 + + ![激活第三方域名](/images/zh/manual/tasks/activate-custom-domain.png#bordered) + + 此时自定义域名状态为“等待 CName 激活”。DNS 解析生效时间可能从几分钟到 48 小时不等。 + +Olares 会自动验证 DNS 记录是否生效。验证通过后，自定义域名状态会变为“已激活”。此时你就可以通过新的 URL `hello.coffee` 访问 Affine 了。 + +::: tip 提示 +若要允许无需登录即可通过自定义域名公开访问应用，请按以下步骤更新访问策略： +1. 前往**设置** > **应用**，点击目标应用。 +2. 点击**入口**，在**创建访问策略**下，将**认证级别**设置为**公开**。 +3. 点击**提交**使变更生效。 + + ![设置认证级别为公开](/images/zh/manual/tasks/set-auth-level-to-public.png){width=50%} +::: \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/developer.md b/docs/zh/manual/olares/settings/developer.md new file mode 100644 index 000000000..8971e7ce7 --- /dev/null +++ b/docs/zh/manual/olares/settings/developer.md @@ -0,0 +1,59 @@ +--- +description: 了解如何利用开发者页面管理仓库、查看系统镜像、导出系统日志以排查问题。 +--- + +# 开发者资源 + +**开发者**页面位于 Olares **设置**项目的底部，专为开发者和高级用户设计，提供了用于管理核心系统资源和诊断问题的工具。包含以下功能： +* **仓库管理** +* **镜像管理** +* **日志导出** + +## 仓库管理 + +**仓库管理** 页面维护了 Olares 下载系统镜像和其他软件包的核心来源仓库。通过此功能，你可以查看已有仓库、添加新仓库、管理现有端点，以优化 Olares 的软件包获取性能。 + +![仓库管理](/images/zh/manual/olares/repo-management.png#bordered) + +在仓库列表页面，您可以查看到已添加的仓库名称、相关镜像数量以及镜像大小。 + +### 添加新仓库 +添加新仓库步骤如下： +1. 从桌面进入**设置** > **开发者** > **仓库管理**。 +2. 点击右上角的 **+ 添加仓库**按钮。 +3. 在弹出的对话框中，填写以下信息： + * **仓库名称**：输入仓库的唯一名称，例如 `docker.io` 或 `quay.io`。 + * **初始 Endpoint**：输入该仓库的初始 URL。 +4. 点击**确认**完成添加。 + +### 管理仓库端点 + +您可以通过添加或排序仓库的访问端点来优化特定仓库的访问速度和稳定性。 + +![端点管理](/images/zh/manual/olares/repo-endpoint-management.png#bordered) + +1. 在**仓库管理**页面列表中，点击目标仓库右侧的 table_edit按钮。 +2. 进入**Endpoint 管理**页面，你可以： + * **排序**：使用上下箭头对端点进行排序。Olares 将按照列表顺序优先使用排在前面的端点。 + * **删除**：点击 delete图标以删除不再需要的端点。 + +## 镜像管理 + +镜像管理功能为您提供了一个全面的视图，用于查看 Olares 系统中所有已下载和缓存的应用程序和软件包镜像。 + +![镜像管理](/images/zh/manual/olares/image-management.png#bordered) + +## 导出系统日志 + +日志记录了各系统组件的运行情况。在排查 Olares 问题时，系统日志可提供关键的诊断信息。要下载系统日志： + +1. 在 Olares 桌面启动**设置** > **开发者** > **日志**。 +2. 点击**收集**生成日志文件。日志将自动保存至默认目录 `/Home/pod_logs`。 +3. 点击**打开**，在新窗口打开日志目录。 + + ![生成日志](/images/zh/manual/olares/export-log.png#bordered) + +4. 右键选择生成的日志文件，点击**下载**将其下载到本地。 + + ![下载日志](/images/zh/manual/olares/download-log.png#bordered){width=70%} +下载后，可在 GitHub 反馈帖中附加日志文件，与 Olares 团队共享以加速问题定位。 diff --git a/docs/zh/manual/olares/settings/gpu-resource.md b/docs/zh/manual/olares/settings/gpu-resource.md new file mode 100644 index 000000000..7e002ee77 --- /dev/null +++ b/docs/zh/manual/olares/settings/gpu-resource.md @@ -0,0 +1,75 @@ +--- +outline: [2, 3] +description: 控制管理和优化 Olares显卡资源，支持单节点或多节点环境下的时间分片、独占和显存分片分配模式。。 +--- + +# 管理显卡使用 + +:::info 注意 +只有 Olares 管理员可以更改显卡使用模式。这样可以确保系统范围内的资源得到最优化管理，避免用户之间的资源需求冲突。 +::: + +Olares 为你提供了强大、灵活的显卡管理功能，让你充分释放 GPU算力，加速大模型推理、图像/视频生成及游戏等高负载任务。不论显卡位于单节点还是跨节点分布，都可在同一界面集中管理。 + +本文档帮你了解并配置显卡分配模式，发挥硬件最大效能。 + +::: tip 注意 +当前仅支持英伟达显卡。 +::: + +## 显卡分配模式 + +Olares 提供三种分配方式，可按场景灵活选择。 + +### 时间分片模式 + +在此模式下，GPU 的处理能力将在多个应用之间共享。 + +- 该模式下，GPU 提供默认的显存资源池。未被分配独占 GPU 或专有显存的应用将自动使用时间分片模式下的 GPU（如可用）。 +- 适合通用型任务以及同时运行多个轻量级应用。 + +### 应用独占模式 + +在此模式下，整个 GPU 的计算能力和显存将专用于单个应用。 + +- 最适合高性能、资源密集型应用，如 AI 图像生成或高性能游戏服务器。 +- 大内存占用可能会限制其他任务的运行。 + +### 显存分片模式 + +在此模式下，GPU 显存（VRAM）被划分为固定配额，分配给指定应用。 + +- 适合同时运行多个显卡密集型应用（如多个 AI 模型），每个应用都有独立显存配额。 +- 可避免多个应用运行在同一 GPU 上时的内存冲突。 + +## 查看显卡状态 + +1. 进入 **设置 > GPU**。GPU 列表显示每个显卡的型号、所在节点、总显存及当前分配模式。 +2. 点击单个显卡以进入其详情页。 + +::: tip 注意 +如果你的 Olares 集群中只有一块 GPU，进入 GPU 页面将直接跳转至详情页；若有多块 GPU，则会显示 GPU 列表。 +::: + +## 配置 GPU + +在 **GPU 详情**页面中，可通过 **GPU 模式** 下拉菜单选择所需模式。不同模式下的配置项略有差异： + +- **时间分片**： + 1. 在 GPU 模式下拉菜单中选择该模式。 + 2. 如有多个 GPU，可在**绑定应用**窗口，点击 **+ 添加应用**，手动将应用绑定到该 GPU。 + ![时间分片](/images/zh/manual/olares/gpu-time-slicing.png#bordered) +* **应用独占**： + 1. 在 GPU 模式下拉菜单中选择该模式。 + 2. 在**选择独占应用**下拉框中选择目标应用。 + 3. 点击**确认**。 + ![独占](/images/zh/manual/olares/gpu-app-exclusive.png#bordered) +- **显存切片**： + 1. 在下拉菜单中选择该模式。 + 2. 在**分配显存**窗口，点击 **+ 添加应用**。 + 3. 选择目标应用，并指定分配给该应用的显存大小（以 GB 为单位）。 + 4. 如需为其他应用分配显存，可重复以上操作，然后点击**确认**。 + ![显存分片](/images/zh/manual/olares/gpu-memory-slicing.png#bordered) + +## 了解更多 +- [监控 Olares 中的显卡使用情况](../resources-usage.md) \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/index.md b/docs/zh/manual/olares/settings/index.md new file mode 100644 index 000000000..126a069db --- /dev/null +++ b/docs/zh/manual/olares/settings/index.md @@ -0,0 +1,19 @@ +--- +description: 使用设置应用管理和配置你的 Olares，包括个性化体验、安全设置、服务集成等功能。 +--- + +# 设置和管理 Olares + +Olares 的**设置**提供了简洁直观的界面，让你轻松配置并管理 Olares。这里是个性化设置、系统安全、服务集成、应用管理等操作的中心入口。 + +设置包含以下功能模块： + +- **安全管理**：管理登录设备和系统安全设置。 +- **账户管理**：创建并管理 Olares 集群中的用户。 +- **应用管理**：监控并配置各个应用的运行状态与行为。 +- **服务集成**：为 Olares 连接外部服务与工具。 +- **外观设置**：设置系统语言与背景等外观选项。 +- **网络配置**：配置 FRP、VPN，并编辑 hosts 文件。 +- **备份与恢复**：创建并管理指定目录的备份与恢复任务。 +- **系统更新**：查看系统详情并执行版本更新。 +- **日志导出**：生成并导出系统日志，用于诊断问题。 diff --git a/docs/zh/manual/olares/settings/integrations.md b/docs/zh/manual/olares/settings/integrations.md new file mode 100644 index 000000000..c1e0c384c --- /dev/null +++ b/docs/zh/manual/olares/settings/integrations.md @@ -0,0 +1,35 @@ +--- +outline: [2, 3] +description: 将 Olares Space 与第三方服务连接，扩展系统功能。了解如何在 Settings 中查看、授权及管理集成服务，实现数据的无缝同步。 +--- + +# 在设置中管理集成 + +设置中的**集成**分区集中展示所有已连接到 Olares 的第三方服务，并支持使用 API 凭证手动配置云对象存储。 + +:::tip 注意 +OAuth 类型的集成以及 Olares Space 需在**LarePass**应用中完成连接，详见 [LarePass 集成文档](../../larepass/integrations.md)。 +::: +## 查看与管理现有集成 + +1. 通过 Dock 或启动台打开**设置**。 +2. 在左侧菜单选择**集成**，即可看到已授权的服务列表。 +3. 点击任一集成卡片查看连接状态和操作选项。 +4. 在**账户设置**页面点击**删除**可移除该集成。 + +## 通过 API 密钥添加云对象存储 + +Olares 支持手动配置 **AWS S3** 和**腾讯云 COS**： + +1. 进入**设置** > **集成**，点击右上角**+ 添加账户**。 +2. 选择 **AWS S3** 或 **Tencent COS**，点击 **确认**。 +3. 在弹出的挂载对话框输入以下信息： + - **Access Key** + - **Secret Key** + - **Region** + - **Bucket name** +4. 点击 **下一步**。凭证验证通过后将显示成功提示。 + +配置完成后，挂载的存储服务将出现在**文件管理器**应用的**云存储**区域。 + +你也可以在 [LarePass](../../larepass/integrations.md#通过-api-密钥添加云盘) 中完成同样的配置。 diff --git a/docs/zh/manual/olares/settings/language-appearance.md b/docs/zh/manual/olares/settings/language-appearance.md new file mode 100644 index 000000000..0aa6e3121 --- /dev/null +++ b/docs/zh/manual/olares/settings/language-appearance.md @@ -0,0 +1,41 @@ +--- +description: 在 Olares 中设置系统语言、切换明暗主题、自定义桌面和登录界面壁纸，打造符合个人习惯的使用环境。 +--- +# 设置语言和外观 + +个性化 Olares 使用体验十分简单。你可以设置首选语言，在浅色和深色主题之间切换，并为桌面和登录屏幕选择自定义壁纸。 + +## 系统语言 + +Olares 当前支持以下语言： +- 英文 +- 中文（简体） + +更改显示语言的方法： + +1. 打开**设置**，在左侧边栏选择**外观**。 +2. 点击下拉菜单，选择语言。 + +## 主题 + +在系统应用中切换浅色和深色主题： + +1. 打开**设置**，在左侧边栏选择**外观**。 +2. 在**主题**面板中，选择**浅色**或**深色**。 + +更改会立即生效。 + +## 壁纸 + +自定义桌面或登录页背景： + +1. 打开**设置**，在左侧边栏选择**外观**。 +2. 在**壁纸**面板中，选择要应用壁纸的位置：桌面或登录背景。 +3. 若要使用内置壁纸，浏览并选择提供的图片。 +4. 若要添加自定义壁纸： + + a. 点击 add_photo_alternate，导航至本地设备的目标文件夹。 + + b. 选择你想要的图片文件。 + + c. 点击**确认**或**打开**将其设置为壁纸。 \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/manage-entrance.md b/docs/zh/manual/olares/settings/manage-entrance.md new file mode 100644 index 000000000..83e07cd21 --- /dev/null +++ b/docs/zh/manual/olares/settings/manage-entrance.md @@ -0,0 +1,62 @@ +--- +outline: [2, 3] +description: 了解如何在 Olares 中管理应用入口，包括设置断点和创建访问策略。 +--- + +# 管理应用入口 + +**入口**定义了用户如何访问 Olares 上的应用。要深入了解，请参阅[入口定义](../../concepts/network.md#入口)。 + +入口设置包括两个部分： + +* **端点设置**：定义应用程序的网络地址和路由配置。 +* **访问策略设置**：控制访问应用程序所需的身份验证方法。 + +## 打开入口设置 + +要管理应用入口： + +1. 导航至**设置** > **应用**， +2. 从列表中点击目标应用，进入应用页面。 +3. 在入口列表中点击目标入口，进入**入口**设置页面。 + +![App 入口](/images/zh/manual/olares/app-entrance.png#bordered) + +## 设置端点 + +**设置端点**页面允许你通过个性化 URL 定义如何从外部访问 Olares 上的应用。 + +选项包括： + +* **端点** – 获取应用域名，例如，`1870a8290.marvin112.olares.cn` (WordPress)。你可以点击复制图标复制 URL。 + +* **默认路由 ID** – 系统为应用分配的路由标识符。例如，WordPress 的默认路由 ID 为`1870a8290`。 + +* **设置自定义路由 ID** – 点击 **+** 图标以使用自定义路由 ID 替换默认路由 ID。例如，将 `1870a8290.marvin112.olares.cn` 更改为 `wordpress.marvin112.olares.cn`。 + +* **设置自定义域名** – 点击 **+** 图标以将你自己的域名（例如，app.yourdomain.com）绑定到此应用程序。你需要按照 DNS 配置步骤完成设置。 + +有关更改应用程序域名的详细说明，请参阅[自定义应用域名](custom-app-domain.md)。 + +## 创建访问策略 + +访问策略控制谁可以访问你的应用以及他们所需的身份验证方法。选项包括： + +* **认证级别**：设置应用的身份验证要求： + + * **公开**：任何人都可以访问，无需登录。 + * **私有**：需要用户登录才可访问。 + * **内部**：如果通过 VPN 访问应用，则无需登录。 + +* **认证模式**：指定验证用户身份的方法： + + * **跟随系统**：继承**我的 Olares**页面中设置的系统身份验证规则。 + * **单因素**：仅需要 Olares 登录密码。 + * **双因素**：需要 Olares 密码以及二次验证码。 + * **无**：无需任何身份验证即可访问。 + +* **子策略**：使用正则表达式对应用程序内的特定路径应用精细的访问规则。 + + 1. 点击**策略**部分中的 **+** 图标。 + 2. 定义特定路径的规则。 + 3. 为每个子策略选择相应的身份验证方法。 \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/manage-team.md b/docs/zh/manual/olares/settings/manage-team.md new file mode 100644 index 000000000..a0b82e15a --- /dev/null +++ b/docs/zh/manual/olares/settings/manage-team.md @@ -0,0 +1,79 @@ +--- +description: 在 Olares 中管理团队成员账户。掌握团队成员添加、权限设置和资源分配方法，提升团队运营效率。 +--- +# 管理多用户 + +Olares 支持多用户。作为管理员，你可以创建并管理团队成员，同时通过高效的资源控制确保系统的最佳性能。 + +## 开始之前 + +请确保： + +* 你拥有 Olares 管理员权限。 +* 系统有足够的可用资源。 +* 团队成员已创建 Olares ID。 + + :::info + 在 Olares 中创建新成员账户时，请确保其 Olares ID 的域名部分与你的一致。 + ::: + +## 创建新成员 + +1. 进入**设置** > **账户**页面。 +2. 点击**创建账户**。 +3. 在对话框中填写必填字段： + - **Olares ID**：仅输入本地名称。 + - **CPU**：分配 CPU 核心（最低 1 核）。 + - **内存**：分配内存（最低 3GB）。 +4. 点击**保存**。 + + 创建完成后，你将看到该 Olares ID 的激活凭据： + - 激活向导 URL + - 一次性密码 + +5. 将激活凭据分享给新成员。 + +你可以在**账户**页面验证他们是否已完成激活。 + +:::tip +新成员无需本地安装 Olares 即可通过激活向导激活账户。 +详细说明请参阅[激活 Olares](../../get-started/activate-olares){target="_blank"}。 +::: + +## 删除成员 + +:::warning +确保用户在删除前备份重要数据——部分数据无法恢复。 +::: + +1. 进入**设置** > **账户**页面。 +2. 点击要删除的成员以查看其账户详情。 +3. 滚动到页面底部，点击**删除用户**。 +4. 在对话框中点击**确定**。 + +## 管理资源配额 + +你可以调整分配给 Olares 集群成员的资源。 + +1. 进入**设置** > **账户**页面。 +2. 点击需要调整资源配额的成员。 +3. 在**账户信息**页面，滚动到底部，点击**修改限制**。 +4. 在对话框中调整 CPU 和内存配额。 +5. 点击**确定**应用更改。 + +## 重置密码 + +1. 进入**设置** > **账户**页面。 +2. 点击需要重置密码的成员。 +3. 在**账户信息**页面，向下滚动，点击**重置密码**。新密码将即刻生成。 +4. 将新密码分享给成员。 + +## 常见问题 + +### 为什么我无法创建新用户？ + +如果你是管理员： + +* 确保新成员已获取其 Olares ID。请参阅[创建 Olares ID](../../get-started/create-olares-id)。 +* 检查你输入的名称是否正确拼写。 +* 确保有足够的系统资源可供分配。 \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/my-olares.md b/docs/zh/manual/olares/settings/my-olares.md new file mode 100644 index 000000000..9322bf788 --- /dev/null +++ b/docs/zh/manual/olares/settings/my-olares.md @@ -0,0 +1,44 @@ +--- +outline: [2, 3] +description: 了解如何利用“我的 Olares”页面管理账户、设备、安全设置及网络访问策略。 +--- + +# 账户与设备管理 + +你可以通过设置中的**我的 Olares** 功能管理 Olares 账户、连接设备和安全策略。点击**设置**页面左上角的个人头像即可进入**我的 Olares**。 + +## Olares Space +在 Olares Space 中查看你的订阅计划详情和使用情况，包括反向代理方案、 +备份、流量消耗等。首次使用时需按提示登录 Olares Space。 + +## 支持与反馈 + +获取帮助资源，或向 Olares 团队提交反馈，改进系统使用体验。 + +## 更改密码 + +更新 Olares 登录密码以增强账户安全性。 + +## 设置网络访问策略 + +定义 Olares 系统的访问策略以控制用户如何连接到你的 Olares。具体操作包括： +- **设置网络可见性**：控制 Olares 服务在网络上的可见程度。选项包括： + * **公开**：服务可供互联网上的任何人访问。 + * **受保护**：服务对外公开，但需要登录才能访问。 + * **私有**：服务不对外公开，只能通过 VPN 访问。 +- **登录安全要求**：设置登录 Olares 的身份验证方式。 + * **双因素**（推荐）：需要你的登录密码和 LarePass 生成的两步验证码，安全性更高。 + * **单因素**：仅需要你的登录密码（安全性较低）。 + +## 查看登录历史 + +查看所有登录 Olares 账户的详细记录。每个登录条目包含登录时间、状态、源 IP 地址和登录原因等信息。 + +## 设备管理 + +**设备**部分允许你查看和管理所有已授权访问 Olares 的设备。每个设备条目都提供有关连接设备的详细信息，例如其名称、操作系统、连接方法、设备 IP 地址和上次连接时间等。 + +可执行的操作包括： + +* **查看设备信息**：点击特定设备以查看其详细信息，包括软件类型、上次活跃时间、位置和令牌详情等。 +* **注销设备**：远程断开设备与 Olares 的连接。该设备需再次登录才能访问 Olares。 diff --git a/docs/zh/manual/olares/settings/remote-access.md b/docs/zh/manual/olares/settings/remote-access.md new file mode 100644 index 000000000..5023d0782 --- /dev/null +++ b/docs/zh/manual/olares/settings/remote-access.md @@ -0,0 +1,45 @@ +--- +outline: [2,3] +description: 了解如何使用设置在 Olares 上配置 VPN，包括强制 VPN 访问、SSH 远程连接与子网路由。 +--- +# 配置 Olares 的专用网络 + +[LarePass 专用网络](../../larepass/private-network.md)为你的 Olares 提供安全的远程访问，即使您身处不同网络或远程位置。Olares 的设置应用为专用网络提供了高级配置，以满足你的特定需求。在这里，您可以强制应用使用专用网络连接、通过专用网络远程实现 SSH 访问，或通过自定义端口路由流量。 + +## 强制使用专用网络 + +为确保安全性，Olares 支持强制使用专用网络，这样会要求所有连接到 Olares 应用的流量均通过专用网络。打开此模式会禁用其他通过反向代理的外部访问流量。 + +启用强制专用网络模式的方法： + +1. 先在两台设备的 LarePass 上（建议一台电脑和一部手机）上开启专用网络。参考[开启专用网络](../../larepass/private-network.md#在-larepass-中启用专用网络)。 +2. 打开设置应用，点击左上角的个人头像，滚动至安全设置。 +3. 打开强制通过 VPN 访问私有入口开关。 + +启用成功后，屏幕底部会显示确认消息。 + +## 允许通过专用网络建立 SSH 连接 +启用此功能后，即使在不同网络或远程工作时，也可以通过 LarePass 专用网络使用 SSH 访问 Olares 设备。 + +1. 打开设置应用，选择**系统** > **VPN**。 +2. 开启**允许通过 VPN 进行 SSH 连接**。端口 **22**（SSH）会自动添加到配置中。 + + ![通过 VPN 使用 SSH](/images/zh/manual/tasks/ssh-via-vpn.png#bordered) + +## 允许子网路由 +启用此功能后，你可以访问与 Olares 位于同一局域网的其他设备。 + +1. 打开设置应用，选择**系统** > **VPN**。 +2. 开启**允许子网路由**。 + +## 配置端口访问的访问控制规则 +启用子网路由后，你可以通过配置访问控制列表（ACL）规则来允许访问特定端口，以便使用所需的网络服务。 + +例如，要通过远程桌面访问 Windows 服务器： +1. 点击 add 打开**添加 ACL**对话框。 +2. 输入 `3389`（远程桌面协议的默认端口），然后点击**确认**。 +3. 点击**应用**使更改生效。 + + ![添加 ACL 端口](/images/zh/manual/tasks/add-acl-port.png#bordered) + +完成配置后，你就可以使用 Windows 远程桌面来访问与 Olares 位于同一局域网的 Windows 服务器了。 \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/restore.md b/docs/zh/manual/olares/settings/restore.md new file mode 100644 index 000000000..359f223a1 --- /dev/null +++ b/docs/zh/manual/olares/settings/restore.md @@ -0,0 +1,60 @@ +--- +description: 通过已有的备份快照将文件恢复至指定目录，或恢复应用数据。文档介绍如何从本地、Olares Space 或 Tencent COS 等位置执行数据还原操作。 +--- + +# 恢复数据 + +你可以通过已有的备份快照，将文件恢复至指定目录，或恢复应用数据。本文档将介绍如何从本地、Olares Space 或 Tencent COS 等位置执行数据恢复操作。 + +## 添加恢复任务 + +添加恢复任务步骤如下： + +1. 进入**设置** › **还原**，点击**添加恢复**。 +2. 根据备份存储位置选择恢复方式。 + + + + + + + +::: tip 提示 +如需从 AWS S3 恢复，请参照 Tencent COS 的操作步骤。可参考 [AWS 文档](https://docs.aws.amazon.com/zh_cn/AmazonS3/latest/userguide/ShareObjectPreSignedURL.html)获取预签名链接的操作方法。 +::: + +## 查看还原任务 + +还原任务创建成功后将显示在还原页面的任务列表中。点击右侧 **>** 按钮进入可查看详细状态。 + +可执行的操作包括： + +- **取消还原任务**：在还原过程中点击**取消**，以中断并取消还原任务。 +- **查看文件或应用**：还原完成后，可直接点击**打开应用** 或**打开文件夹**。 diff --git a/docs/zh/manual/olares/settings/roles-permissions.md b/docs/zh/manual/olares/settings/roles-permissions.md new file mode 100644 index 000000000..6c1ffd99d --- /dev/null +++ b/docs/zh/manual/olares/settings/roles-permissions.md @@ -0,0 +1,47 @@ +--- +description: Olares 团队中的用户角色和权限体系说明。了解不同角色的权限范围，确保团队成员安全高效协作。 +--- +# 用户角色与权限 + +Olares 支持多用户操作，允许多个用户同时访问系统。每位用户可以根据分配的角色和权限安全访问资源。 + +## 角色类型 + +Olares 提供两种默认用户角色： +- **管理员 (Admin)**：首次激活并登录 Olares 的用户为管理员。 +- **成员 (Member)**：标准用户角色，权限受限。 + + + + + + + + + + + + + + +
角色权限
成员 +
    +
  • 使用系统应用：文件管理器、Vault、Wise、Profile、仪表盘和控制面板
    • +
  • 启用专用网络访问私有入口
    • +
  • 连接 Olares Space
    • +
  • 自定义应用入口
    • +
  • 在应用市场中安装常规应用
    • +
  • 访问具有分配读/写权限的共享 Vault
    • +
  • 在控制面板中查看基本系统状态
    • +
+
管理员 + 成员的所有权限，此外还包括： +
    +
  • 创建和管理用户账户
    • +
  • 管理 Vault 团队，创建共享 Vault，并为共享 Vault 分配读/写权限
    • +
  • 安装和管理共享应用
    • +
  • 监控和管理系统资源
    • +
  • 设置 GPU 使用模式
    • +
  • 更新 Olares
    • +
+
\ No newline at end of file diff --git a/docs/zh/manual/olares/settings/set-up-hosts.md b/docs/zh/manual/olares/settings/set-up-hosts.md new file mode 100644 index 000000000..6e1249676 --- /dev/null +++ b/docs/zh/manual/olares/settings/set-up-hosts.md @@ -0,0 +1,48 @@ +--- +description: 在 Olares 中修改 Hosts 配置，解决网络访问限制问题。配置 IP 映射和验证解析的方法，确保应用正常访问外部资源。 +--- +# 修改 Hosts 配置 + +运行应用时，可能需要访问特定网站（例如 GitHub）来下载资源或获取数据。然而，由于网络环境的限制，这些网站可能无法正常访问。为了解决这一问题，Olares 支持通过系统设置更新系统 Hosts 文件（例如添加 GitHub 的 IP 映射），以支持 Olares 在运行时访问特定网站。 + +## 如何修改 Hosts 配置 + +1. 打开**设置**，进入**系统** > **Hosts**。 +2. 右上角点击**添加 Hosts**，输入域名和对应的 IP 地址： + - **Host 名称**：输入目标网站的域名，例如 `github.com`。 + - **IP 地址**：输入对应的 IP 地址，例如 `20.205.243.166`。 + + ![添加 Host](/images/zh/manual/tasks/add-host.png#bordered) + +3. 点击**确认**保存变更。 + +:::info DNS 缓存延迟 +由于可能存在 DNS 缓存，Hosts 地址配置后可能需要等待一段时间才能生效。 +::: +## Hosts 配置示例 +以下是 GitHub 网站的常用 Hosts 配置： + +| Host 名称 | IP 地址 | +|-------------------------|------------------| +| `github.com` | `20.205.243.166` | +| `raw.githubusercontent.com` | `185.199.111.133` | + +:::tip 查找可用 GitHub Hosts +示例的 IP 地址可能会随时间变化，请以 [https://hosts.gitcdn.top/hosts.txt](https://hosts.gitcdn.top/hosts.txt) 网站提供的最新地址为准。 +::: + +## 验证 Hosts 配置 + +在运行应用之前，可以使用 `nslookup` 命令来验证域名是否已正确解析为配置的 IP 地址。 + +打开命令提示符或终端，输入以下命令，替换 `[domain-name]` 为要验证的域名： + ```shell + nslookup [domain-name] + ``` +查看输出结果。例如： + ```shell + Name: github.com + Address: 20.205.243.166 + ``` + +确认 `Address` 字段是否与配置的 IP 地址一致。如果一致，则说明修改已生效。 \ No newline at end of file diff --git a/docs/zh/manual/olares/settings/update.md b/docs/zh/manual/olares/settings/update.md new file mode 100644 index 000000000..be94c82fe --- /dev/null +++ b/docs/zh/manual/olares/settings/update.md @@ -0,0 +1,41 @@ +--- +description: 了解如何升级 Olares 版本，保持系统功能和安全性。 +--- +# 更新 Olares + +Olares 定期发布新版本，带来功能改进和用户体验优化。本文档说明如何检查和安装系统更新。 + +:::info 仅管理员可以升级 +只有 Olares 管理员可以执行系统更新。更新将应用于同一 Olares 集群内的所有成员。 +::: + +:::tip 提示 +有关 Olares 的版本控制实践及当前跨次版本升级（比如从 `1.10.5` 升到 `1.11.0`）的限制，请参阅 [Olares 版本说明](../../../developer/install/versioning.md)。 +::: + +## 检查并安装更新 +:::tip 提示 +在更新前，请查看发布说明以了解新功能和重要更改。 +::: + +1. 打开**设置** > **我的 Olares** > **当前版本**。 +2. 如果有可用的新版本，点击**立即升级**。 + +更新完成后，系统将显示确认消息。 + +## 手动升级 `olaresd` + +`olaresd` 是 Olares 系统的核心守护进程，负责提供多种关键系统管理功能。在某些情况下，升级 Olares 版本之后，可能还需要手动升级 `olaresd` 以解决某些服务无法正常访问的问题。 + +参考版本对应的[发布说明](https://github.com/beclab/Olares/releases/)，确认是否需要手动升级。 + +要手动升级 `olaresd`： + +1. 打开控制面板，左侧点击**终端** > **Olares**。 + ![Open terminal in Olares](/images/zh/manual/tasks/olares-terminal-in-control-hub.png#bordered) +2. 在终端中执行以下命令： + ```bash + curl -SsfL https://cdn.joinolares.cn/upgrade_1_11_6.sh | bash - + ``` + 其中： + - `1_11_6` 表示将 `olaresd` 和 `olares-cli` 升级到 `1.11.6` 版本。 \ No newline at end of file diff --git a/docs/zh/manual/olares/team.md b/docs/zh/manual/olares/team.md new file mode 100644 index 000000000..15d2e78e0 --- /dev/null +++ b/docs/zh/manual/olares/team.md @@ -0,0 +1,48 @@ +--- +description: 在 Olares 中创建和管理协作团队环境。了解多用户模式优势，掌握资源共享和团队协作方法，实现高效的团队管理。 +--- +# 创建团队 + +想与家人、朋友或同事共享 Olares 吗？以下是创建协作 Olares 环境所需了解的一切。 + +## 为什么选择 Olares 团队模式 + +Olares 的多用户设计能够高效共享系统资源，避免了每增加一个新用户就需要部署额外系统的重复工作。 + +与他人共享 Olares 时，你可以： + +* 利用专业级开源替代方案构建强大的工作空间，无需订阅费用。 +* 让每个人都能使用资源密集型应用而不增加系统开销。 +* 为团队构建一个文件、照片和文档的共享库，随时随地安全访问。 +* 存储并管理共享的文件、照片和文档。 + +借助 Olares 中丰富的应用，你可以根据团队的工作和协作需求定制环境。 + +## Olares 集群 + + Olares 创建了一个基于 Kubernetes 的环境，可以高效支持多用户并最大限度减少系统开销。安装设置后，你的设备将成为一个私人服务器，供所有人安全访问。 + +## 你作为管理员的角色 + +作为 Olares 管理员，你主要负责： + +* 管理团队成员的用户账户 +* 安装和维护系统范围内的共享应用 +* 确保系统资源的公平分配 + +--- + +
+

用户角色和权限

+了解 Olares 中的不同角色。 +
+ +
+

管理你的团队

+为你的团队成员设置账户。 +
+ +
+

在 Olares 中协作

+学习如何邀请和与团队成员互动。 +
\ No newline at end of file diff --git a/docs/zh/manual/olares/vault/index.md b/docs/zh/manual/olares/vault/index.md new file mode 100644 index 000000000..171be9fc1 --- /dev/null +++ b/docs/zh/manual/olares/vault/index.md @@ -0,0 +1,41 @@ +--- +description: 使用 Vault 安全存储和管理敏感数据。了解端到端加密功能和跨设备同步，轻松管理密码、数字身份和一次性密码。 +--- +# 密钥管理 + +Vault 是 Olares 中的密码管理器，旨在安全存储和管理敏感数据。通过 Vault，你可以安全地存储和组织私钥与密码、数字身份 (DIDs) 、Olares ID、一次性密码 (OTPs) 以及其他机密数据。 + +Vault 的关键功能包括： +* 端到端加密，确保最高安全性 +* 私有和共享 Vault，满足个人与组织需求 +* 跨设备的无缝同步 +* 自动填充功能，轻松输入凭据 +* 支持 2FA（双因素认证），管理 OTP + +## 客户端 + +Vault 的服务器组件运行在 Olares 上，同步单个用户的多个客户端设备。数据在传输和存储过程中使用私钥加密，确保安全性。 +你可以通过 Olares 使用 Vault，也可以通过移动设备、桌面和浏览器扩展的 LarePass 客户端访问，实现跨平台一致的用户体验。 + +访问 [LarePass 页面](https://olares.cn/larepass) 获取 LarePass 的详细信息和下载选项。 + +--- +
+

Vault 基本操作

+了解 Vault 项目及基本操作，学习如何在 Vault 中安全存储和管理敏感数据。 +
+ +
+

共享 Vault 项目

+学习如何管理团队 Vault 访问权限，以及使用共享 Vault。 +
+ +
+

设置双因素认证代码

+学习如何生成并存储 2FA 代码以增强安全性。 +
+ +
+

使用 LarePass 的自动填充功能

+学习如何设置和使用自动填充功能，适配不同的 LarePass 客户端。 +
\ No newline at end of file diff --git a/docs/zh/manual/olares/vault/share-vault-items.md b/docs/zh/manual/olares/vault/share-vault-items.md new file mode 100644 index 000000000..1ba3e525b --- /dev/null +++ b/docs/zh/manual/olares/vault/share-vault-items.md @@ -0,0 +1,83 @@ +--- +outline: [2, 3] +description: 在 Olares 中安全共享 Vault 项目。了解团队角色权限设置，管理共享 Vault 访问权限，实现团队成员间的安全协作。 +--- + +# 共享 Vault 项目 + +共享 Vault 是在同一 Olares 集群内组织、管理和安全共享数据的有效方法。无论是管理家庭账户还是企业级数据，团队 Vault 都能让你兼顾安全性与协作。 + +## 了解团队角色 + +:::info 提示 +Olares 管理员会自动成为共享 Vault 的所有者。 +::: + +| 角色 | 所有者 | 管理员 | 成员 | +|-----------------------------------|-------|-------------|--------| +| 添加、暂停、重新激活成员 | ✅ | ✖️ | ✖️ | +| 指定管理员 | ✅ | ✖️ | ✖️ | +| 创建共享 Vault 条目 | ✅ | ✅️ | ✖️ | +| 分配读/写权限 | ✅ | ✅ | ✖️ | + +## 设置团队访问 + +### 确认成员资格 + +所有 Olares 集群的管理员和用户会自动加入一个 Vault 团队。但出于安全原因，每位新成员在访问团队 Vault 条目前必须完成验证。 + +1. 在 Vault 中，导航到**我的团队** > **邀请**页面。 +2. 点击成员账户名称查看邀请码。 + + ![Invite members](/images/manual/olares/invite-members.png#bordered) + +3. 将邀请码发送给相应的成员。 + :::tip 提示 + 对于成员，在 Vault 中的**邀请** > **我的团队**页面接受邀请。 + ::: +4. 在成员确认邀请后，返回邀请页面并点击**添加成员**。 + +### 设置管理员 + +1. 在 Vault 中，导航到**我的团队** > **成员**页面。 +2. 从成员列表中选择一个成员。 +3. 点击右上角的 more_horiz，选择**设为管理员**。 +4. 若需移除管理员权限，选择**移除成员**。 + +### 暂停成员 + +1. 在 Vault 中，导航到**我的团队** > **成员**页面。 +2. 从成员列表中选择一个成员。 +3. 点击右上角的 more_horiz，选择**暂停**。 +4. 若需重新激活成员，选择**取消暂停**。 + +:::tip 提示 +暂停的成员保留其角色，但无法接收更新或进行更改。重新激活需再次验证以确保安全。 +::: + +## 使用共享 Vault + +共享 Vault 专为在多个 Olares 用户间共享数据设计。默认情况下，必须由 Olares 管理员创建。 + +### 创建共享 Vault + +1. 在 Vault 中，导航到**我的团队** > **Vaults** 页面。 +2. 点击右上角的 add，输入 Vault 名称。 +3. 点击**保存**。 + +### 编辑共享 Vault 权限 + +1. 在 Vault 中，导航到**我的团队** > **Vaults** 页面。 +2. 选择要编辑权限的共享 Vault，可以添加或移除成员并设置读/写权限。 +3. 点击**保存**。 + +### 删除共享 Vault + +:::warning 警告 +删除共享 Vault 将永久移除所有相关数据。请务必在确认删除前仔细检查。 +::: + +1. 在 Vault 中，导航到**我的团队** > **Vaults** 页面。 +2. 选择共享 Vault 查看其详情。 +3. 点击右上角的 more_horiz，选择**删除**。 +4. 在弹出对话框中输入 `DELETE` 以确认删除。 diff --git a/docs/zh/manual/olares/vault/vault-items.md b/docs/zh/manual/olares/vault/vault-items.md new file mode 100644 index 000000000..f01a8b1ea --- /dev/null +++ b/docs/zh/manual/olares/vault/vault-items.md @@ -0,0 +1,179 @@ +--- +outline: [2, 3] +description: 了解 Olares 系统应用 Vault 的基本操作。学习创建和管理 Vault 项目，使用标签组织内容，通过快速筛选功能高效管理敏感数据。 +--- + +# Vault 基本操作 + +本文档将带你了解 Vault 的基础使用方法，从设置第一个 Vault 到高效地组织你的敏感数据。 + +## 了解 Vault 组件 + +### Vault 类型 + +Olares 为用户提供两种主要类型的 Vault： + +* 主 Vault（**我的 Vault**）：账户激活时自动创建，作为用户的私人 Vault。使用用户助记词加密以确保最大安全性。 +* 共享 Vault（**Team Vault**）：Olares 内的协作 Vault，支持团队成员或家庭之间安全共享信息。 + +### Vault 项目 + +Vault 项目是存储敏感信息的独立安全容器。每个 Vault 项目包含以下字段： + +* **名称**：便于识别的标题。 +* **标签**：用于组织和快速筛选。 +* **字段**：存储不同类型信息的数据区域。 +* **历史记录**：记录项目修改信息。 +* **附件**：添加相关文件。 +* **过期时间**：为时间敏感的信息设置过期日期。 + +目前，Vault 支持以下项目类型： +- 网站/应用 +- 计算机 +- 信用卡 +- 银行账户 +- Wi-Fi 密码 +- 护照 +- 验证器 +- 文档 +- 自定义 + +### 字段 + +字段是 Vault 项目的核心组件，支持存储多种数据类型，包括： + +* 用户名 +* 密码 +* 助记词 +* 电子邮件地址 +* URL +* 日期和月份 +* 信用卡号 +* 电话号码 +* PIN +* 明文 +* 一次性密码 (OTP) + +## 使用密码保护 Vault + +首次在 Olares 中使用 Vault 时，系统会提示你设置本地密码。此密码不应与你的 Olares 登录密码相同。 + +1. 为 Vault 设置本地密码。 +2. 使用助记词短语导入已与 Olares 服务器关联的 Olares ID。 + +![Vault password](/images/manual/olares/vault-local-password.png) + +:::tip 提示 +如果你不知道助记词短语的位置，请参阅[备份助记词短语](../../larepass/back-up-mnemonics)。 +::: + +## 管理 Vault 项目 + +:::tip 提示 +从一开始就使用描述性名称和相关标签来组织 Vault 项目。随着 Vault 项目数量增加，这种做法会越来越有价值。 +::: + +### 添加 + +要添加 Vault 项目： + + + + + + + + +### 编辑 + +:::info 提示 +LarePass 浏览器扩展不支持编辑 Vault 项目。如需完整编辑功能，请使用 Olares 的 Vault 应用或 LarePass 的移动或桌面版本。 +::: + +在编辑模式下，你可以： +- 更新必填字段。 +- 为项目添加标签以便组织和筛选。 +- 设置过期时间。 +- 添加文件附件（每个文件不得超过 1 MB）。 +- 查看并恢复历史记录。Vault 为每个项目保留多达 10 条记录，超过限制时会删除较旧的记录。 + +**编辑 Vault 项目**： + +1. 在 Vault 中选择需要编辑的项目。 +2. 在项目的详情窗口或页面中，点击右上角的 edit_note 进入编辑模式。 +3. 对项目详情进行必要的修改。 +4. 点击**保存**。 + +### 收藏 Vault 项目 + +重要项目可以标记为收藏，便于快速访问。 + + + + + + + +## 筛选 Vault 项目 + +你可以使用快速筛选或搜索框找到所需的 Vault 项目。 + +### 快速筛选 + +* 按主 Vault 和共享 Vault：选择**我的 Vault** 或**团队 Vault** 快速找到项目。 +* 按标签：点击标签名称轻松定位已标记的 Vault 项目。 +* 按收藏：点击**收藏**列出所有收藏项目。 +* 按最近使用：点击**最近使用**显示你的最近项目。 +* 按附件：点击**附件**显示所有带有附件的项目。 + +### 关键词搜索 + +点击 search 使用关键词直接搜索目标项目。 \ No newline at end of file diff --git a/docs/zh/manual/olares/wise/basics.md b/docs/zh/manual/olares/wise/basics.md new file mode 100644 index 000000000..e5d271f57 --- /dev/null +++ b/docs/zh/manual/olares/wise/basics.md @@ -0,0 +1,111 @@ +--- +outline: [2, 3] +description: 了解 Olares 系统应用 Wise 的基本操作。学习收集、阅读和组织内容，使用标签和笔记功能，追踪阅读进度，实现个性化阅读体验。 +--- +# Wise 基本操作 + +Wise 为你提供内容管理提供灵活丰富的选项，帮你轻松收集、阅读、管理内容。你可以通过本页面学习 Wise 的基本操作。 + +## 将内容添加到你的库 +通过以下方法保存感兴趣的内容。 + +### 添加到收件箱或稍后阅读 +你可以使用以下两个内容集组织你的阅读流程： + +* **收件箱**：你计划近期阅读的主要内容集合。 +* **稍后阅读**：你计划稍后查看的内容。 + +在浏览标题或阅读内容时，点击 **inbox 收件箱** 或 **schedule 稍后阅读**，将内容保存到相应的集合。 + +![Inbox or Read later](/images/manual/olares/inbox-read-later.png) + +### 通过 LarePass 收藏网页 + + + + + + + + +### 手动添加内容 +Wise 支持包括视频、音频、PDF 和电子书在内的多种内容类型： + +1. 在菜单栏中点击 add_circle。 +2. 添加网页时，选择**网页**。 +3. 添加下载链接时，选择**下载链接**。 +4. 添加本地的 PDF 或电子书（EPUB 格式）时，选择**上传**。 +5. 添加 RSS 订阅源时，选择 **RSS**。 + :::tip 提示 + 要了解如何通过 Wise 订阅 RSS，请参阅 [订阅 RSS 订阅源](subscribe.md)。 + ::: + +## 自动下载 +Wise 会自动为新的音频或视频内容创建下载任务，将媒体文件保存到 Olares 以便离线访问。 + +此功能可以： + +* 确保内容始终可离线访问 +* 防止原始来源不可用时内容丢失 +* 提供对媒体文件的快速访问 + +要查看所有下载的媒体文件，前往 settings > **传输** > **下载**。该页面会显示你的下载内容及其详细信息。 +![已下载的媒体文件](/images/manual/olares/downloaded-media-files.png#bordered) + +点击 folder_open 图标可以在**文件管理器**中找到对应的文件。 + +## 组织你的阅读 + +### 使用标签进行组织 + +你可以通过标签创建结构化的内容集合： + +1. 在列表页面中，点击内容卡片上的 sell。 +2. 在标签输入框中，选择或创建与当前内容相关的标签。 + +![标签](/images/manual/olares/tags.png#bordered) + +你可以在settings > **标签**页面找到并管理你的标签。 + +### 用笔记捕捉灵感 + +1. 在阅读时，点击 right_panel_open 打开 **信息** 面板。 +2. 在**笔记**部分输入你的想法。 +3. 点击**保存**存储笔记。 + +你可以稍后编辑或删除笔记。 + +![笔记](/images/manual/olares/notes.png#bordered) + +### 跟踪你的阅读进度 + +Wise 使用文章封面上的绿色点标识未读内容。当你打开一篇文章时，它会自动标记为已读。 + +在阅读时，你可以通过工具栏手动在 **playlist_add_check 已看** 和 **playlist_remove 未看** 状态之间切换，以维护你的阅读进度。 + +### 搜索 Wise 中的内容 + + +## 更改主题 +默认情况下，Wise 会跟随系统的浅色/深色主题设置。你可以根据个人喜好更改： + +1. 左下角点击 settings，选择**偏好设置**。 +2. 在**主题**选项下，选择你喜欢的显示模式： + - 浅色 + - 暗黑 + +## 了解更多 +- [使用 Wise 打造知识中枢](../../best-practices/organize-content.md) \ No newline at end of file diff --git a/docs/zh/manual/olares/wise/filter-examples.md b/docs/zh/manual/olares/wise/filter-examples.md new file mode 100644 index 000000000..123d035e6 --- /dev/null +++ b/docs/zh/manual/olares/wise/filter-examples.md @@ -0,0 +1,55 @@ +--- +description: 本文介绍如何利用 Wise 的高级筛选功能，帮助你更好地管理、分类和查找已保存的内容。通过具体示例，讲解如何处理未读内容、回顾历史文章等实际应用场景。 +--- + +# 过滤视图示例 +本文提供了一系列 Wise 查询示例。每个示例都对应一个具体场景，帮助你更好地整理、排序和重新发现库中的内容。 + +## 查看特定订阅源的未读内容 +想要追踪某个订阅源的更新？使用这个查询来显示该来源的所有未读条目： +``` +feed_id:12345 AND seen:false +``` + +## 查看特定作者的所有内容 +轻松找出特定作者的所有文章： +``` +author:张三 +``` +这样就能看到作者为“张三”的所有文章，持续关注作者的创作。 + +## 跟进最新内容 +只想看新文章？你可以按发布日期筛选内容： +``` +published_at__gt:2025-04-01 +``` +这个查询显示 2025 年 4 月 1 日之后发布的条目，避免被历史文章分散注意力。 + +## 查看带笔记的收藏内容 +使用以下查询查找带有标签且包含你的笔记的条目： +``` +tag:AI AND has:note +``` +这对重温那些你添加了个人想法或评论的收藏内容特别有用。 + +## 优先处理重要文章 +需要专注于特定主题？这个查询可以显示“稍后阅读”列表中特定标签的内容： +``` +tag:工作 AND location:readlater +``` +这样就能找出所有标记为“工作”且保存在“稍后阅读”列表中的内容，便于集中处理重要内容。 + +## 整理未看的视频内容 +RSS 订阅源里的视频攒了不少？用这个查询筛选未看的视频： +``` +file_type:video AND seen:false AND isfeed:true +``` +这样就能列出订阅源中所有未看的视频，方便集中观看或整理。 + +## 找出长期未读的内容 +想翻翻以前收藏的效率文章？这个查询可以帮你找出来： +``` +last_opened__lt:2023-12-31 AND tag:效率 +``` + +这会显示所有最后打开时间在 2023 年 12 月 31 日之前的条目。你可以重新查看这些保存的效率相关内容，或者决定是否要删除它们。 \ No newline at end of file diff --git a/docs/zh/manual/olares/wise/filter-syntax-guide.md b/docs/zh/manual/olares/wise/filter-syntax-guide.md new file mode 100644 index 000000000..2ab5b4af2 --- /dev/null +++ b/docs/zh/manual/olares/wise/filter-syntax-guide.md @@ -0,0 +1,145 @@ +--- +outline: [2,4] +description: 介绍 Wise 过滤视图的关键语法规则。 +--- +# 过滤语法参考 + +过滤视图是整理条目的强大工具。你可以使用各种参数和运算符自定义查询。 + +## 查询结构 +创建单个条件的查询时，只需指定参数和对应的值即可。 + +**示例**： +``` +feed_id:12345 +``` + +你也可以使用逻辑运算符组合多个参数。 + +### `AND` +使用 `AND` 连接多个参数，查询结果需要满足**所有**条件。 + +**示例**： + +获取未读**且**标记为“稍后阅读”的条目： +``` +location:readlater AND seen:false +``` + +### `OR` +使用 `OR` 连接多个参数，查询结果只需满足**其中一个**条件。 + +**示例**： + +获取来自书库**或**最后打开时间早于 2023 年 1 月 1 日的条目： +``` +islibrary:true OR last_opened__lt:2023-01-01 +``` + +### 复合条件 +可以使用 `AND` 和 `OR` 组合多个条件，并用括号 `()` 指定运算优先级。 + +**示例**： + +以下查询会返回所有未读条目中，要么在收件箱中，要么标记为“稍后阅读”的内容： +``` +seen:false AND (location:inbox OR location:readlater) +``` + +### 特殊符号 +如果过滤条件中包含特殊符号（如空格、冒号等）时，使用半角双引号`""`将其括起来（半角双引号除外）。例如： +``` +tag:"学习/AI" +``` +``` +author:"Arthur C. Clarke" +``` +## 参数 + +### 基础参数 +参数和值之间用半角冒号连接（`参数:值`）即可设置筛选条件。 + +#### `feed_id` +条目所属的订阅源 ID。 +可以在 settings > **RSS 订阅源**页面查看订阅源 ID。 + +#### `author` +条目作者。 + +#### `file_type` +条目的文件类型。 +可用的文件类型包括： +- `article` +- `video` +- `audio` +- `ebook` +- `pdf` + +### 时间参数 +时间参数需要加上运算符（`参数__运算符:值`），日期格式为 `YYYY-MM-DD`。 + +#### `published_at` +条目发布时间。 + +#### `created_at` +条目创建时间。 + +#### `updated_at` +条目最后更新时间。 + +#### `last_opened` +条目最后打开时间。 + +#### 运算符 +可用的运算符包括： +- `__gt`（大于）
+ 获取时间**晚于**指定日期的条目。 + +- `__gte`（大于等于）
+ 获取时间**等于或晚于**指定日期的条目。 + +- `__lt`（小于）
+ 获取时间**早于**指定日期的条目。 + +- `__lte`（小于等于）
+ 获取时间**等于或早于**指定日期的条目。 + +### 布尔参数 +使用 `字段名:true/false` 格式根据真/假值筛选条目。 + +#### `islibrary` +条目是否来自“库”。 + +#### `isfeed` +条目是否来自订阅源。 + +#### `seen` +条目是否已读。 + +### 位置参数 +根据条目位置进行筛选。 + +#### `location` +指示条目的位置。 + +可用值包括： +- `all`：所有条目。 +- `readlater`：标记为“稍后阅读”的条目。 +- `inbox`：收件箱中的条目。 + +### 相关内容参数 +根据条目是否包含特定相关内容进行筛选。 + +#### `has` +使用 `has` 参数筛选包含特定内容的条目。 + +可用值包括： +- `note`：是否包含笔记。 +- `tag`：是否包含标签。 + +#### `tag` +按特定标签名称筛选条目。 + +#### `tag_id` +按特定标签的唯一 ID 筛选条目。 +可以在 settings > **标签**页面查看标签 ID。 \ No newline at end of file diff --git a/docs/zh/manual/olares/wise/filter.md b/docs/zh/manual/olares/wise/filter.md new file mode 100644 index 000000000..db1ed38b2 --- /dev/null +++ b/docs/zh/manual/olares/wise/filter.md @@ -0,0 +1,55 @@ +--- +description: 了解如何使用 Wise 强大的过滤系统来整理你的内容库。创建基于标签的视图、添加自定义过滤视图，并使用高级查询参数来高效管理内容。 +--- +# 通过过滤视图组织内容 + +随着 Wise 内容库的不断扩大，保持内容整理变得越来越有挑战。通过过滤视图，你可以基于标签、保存日期、作者等参数快速找到并管理所需内容。 + +本指南涵盖以下内容： +- 从标签和订阅源创建过滤视图。 +- 使用查询添加自定义过滤视图。 + +:::info +过滤功能仅适用于 **inbox 收件箱**和 **schedule 稍后阅读** 和订阅源中的内容。 +::: + +## 使用标签或订阅源过滤条目 +过滤视图可以让你基于标签或订阅源对内容进行分组整理。这样可以快速访问与特定主题或来源相关的内容。 + +1. 打开 Wise，点击左下角的 settings。 +2. 根据需要选择： + - **标签**——按特定主题或类别过滤内容。 + - **RSS 订阅源**——按特定来源过滤内容。 +3. 对于已有的标签，点击**管理视图...**。你可以： + - 将该标签或订阅源的内容添加到现有视图中，或者 + - 创建新视图来组织所有相关内容。 + + ![从订阅源过滤条目](/images/zh/manual/tasks/filter-entries-from-feed.png#bordered) +4. 如果要创建新视图： + - 输入视图名称（如 `技术文章`）。 + - 点击**确认**保存视图。 + +## 添加自定义过滤视图 +除了基本的过滤方式，你还可以使用查询语言来创建更精准的自定义视图。比如，你可以设置多个条件来筛选特定内容，让分类更加细致。 + +下面演示如何使用查询语言为"AI"标签创建视图： + +1. 打开 Wise，左下角点击 settings， 选择**过滤视图**。 +2. 在右上角点击**添加视图**。 +3. 输入视图名称（如"AI 趋势"），在**查询**字段中输入 `tag:AI`。 +4. 点击**确认**，保存视图。 + + ![添加过滤视图](/images/zh/manual/tasks/add-filtered-view.png#bordered){width=70%} +## 将视图固定到侧边栏 +你可以通过以下任一方式将过滤视图固定到侧边栏： + +- 在列表中找到该视图，点击对应**操作**栏中的 keep。 +- 打开过滤视图，点击标题栏中的 keyboard_arrow_down，选择**固定至边栏**。 + + ![固定到侧边栏](/images/zh/manual/tasks/pin-to-sidebar.png#bordered){width=50%} + +## 可用过滤器 +要了解所有可用的过滤选项及其使用方法，请参考以下内容： + +- [过滤视图示例](filter-examples.md) +- [过滤语法参考](filter-syntax-guide.md) \ No newline at end of file diff --git a/docs/zh/manual/olares/wise/index.md b/docs/zh/manual/olares/wise/index.md new file mode 100644 index 000000000..684765849 --- /dev/null +++ b/docs/zh/manual/olares/wise/index.md @@ -0,0 +1,33 @@ +--- +description: 使用 Wise 智能内容聚合平台，利用本地优先和 AI 驱动功能，在 Olares 中创建个性化信息中心，实现跨平台内容的智能管理与推荐。 +--- +# 使用 Wise 一站式聚合、管理内容 + +Wise 是一款以本地优先和 AI 驱动的现代阅读器，是 Olares 生态系统中的核心应用之一。它帮助你从各种平台收集、阅读和管理信息，从而创建并维护个人信息中心。 + +关键功能包括： + +* **自托管推荐算法**：你可以运行个性化算法过滤和排序在线内容，打破信息茧房，接收多样化和个性化的内容推荐。 +* **跨平台内容聚合**：Wise 集成文章、视频、音频及其他多媒体内容，为你提供全面的阅读体验。 +* **无缝书签功能**：通过 LarePass 浏览器扩展，你可以一键将网页保存到 Olares，随时访问和管理内容。 + +--- +
+

Wise 基础知识

+了解 Wise 中收集、阅读和管理内容库的基本操作。 +
+ +
+

发现主题内容

+了解 Wise 中的自托管推荐算法如何工作。 +
+ +
+

订阅和管理订阅源

+通过 RSS 订阅、手动订阅和 LarePass 浏览器扩展设置并组织你的内容来源。 +
+ +
+

添加过滤视图

+了解如何使用过滤视图，根据标签、作者或发布日期等条件来整理和显示内容。 +
\ No newline at end of file diff --git a/docs/zh/manual/olares/wise/recommend.md b/docs/zh/manual/olares/wise/recommend.md new file mode 100644 index 000000000..973542865 --- /dev/null +++ b/docs/zh/manual/olares/wise/recommend.md @@ -0,0 +1,54 @@ +--- +description: 了解如何在 Olares 中安装 Wise 的本地推荐算法。在保护隐私的同时获得个性化内容推荐，监控和管理推荐工作流程。 +--- +# 本地推荐算法 +大多数数字平台通过集中式推荐系统控制你看到的内容，这些系统会收集并分析你的数据。Wise 提供了不同的方式——你可以直接在设备上选择并运行推荐算法，在享受个性化内容发现的同时，确保你的阅读偏好和交互完全私密。 +## 自托管推荐如何工作 +Wise 中的内容推荐分为两个阶段： + +1. 内容提供商在云端收集并打包全球内容。 +2. 你的 Olares 设备下载这些内容，并使用你选择的推荐算法在本地处理。 + +由于每个设备接收相同的内容数据并离线处理推荐，你的阅读偏好和交互数据始终保持私密。你还可以通过可视化界面监控推荐工作流，清楚了解内容的处理过程。 + +随着你在 Wise 中持续阅读和收藏内容，算法会学习你的偏好，并逐步提高推荐的准确性。 + +## 安装推荐算法 + +通过以下步骤接收个性化内容推荐： + +1. 在**应用市场**中浏览**推荐算法**类别，选择感兴趣的主题。 +2. 点击**获取**安装你选择的算法。 +3. 等待算法完成本地推荐工作流。 + + ![Recommendation algorithm](/images/manual/olares/install-recommendation.png#bordered) + +安装完成后，你可以在 Wise 的**为你推荐**页面查看推荐内容。此页面显示所有已安装推荐算法的结果，并按算法分为独立内容流。点击顶部的推荐标题即可切换不同算法。 + +![For you](/images/manual/olares/for-you.png#bordered) + +:::tip 提示 +你可以订阅内容源，以便未来阅读该来源的所有内容。 +::: + +## 监控算法工作流 +你可以查看推荐引擎如何处理数据并生成内容推荐： + +1. 在 Wise 中，左下角点击settings，选择**推荐算法**。 +2. 点击任一特定工作流以查看其操作记录。 +3. 点击记录查看详细信息和日志。 + +![Recommendation algorithm workflow](/images/manual/olares/recommendation-algorithm-workflow.png#bordered) + +工作流可视化显示推荐过程的每个步骤。你可以检查步骤摘要、容器设置和操作日志，确保完全透明。 + +## 卸载推荐算法 +卸载推荐算法的方法： + +1. 在**应用市场**中进入**我的 Olares** 页面。 +2. 点击应用操作按钮旁的 keyboard_arrow_down，选择**卸载**。 + +## 常见问题 + +### 为什么安装推荐算法后看不到推荐内容？ +如果你刚安装推荐算法，需要稍等片刻，等待算法在 Olares 上完成本地推荐工作流。这种方式确保所有处理均在本地进行，以保护你的隐私。 \ No newline at end of file diff --git a/docs/zh/manual/olares/wise/subscribe.md b/docs/zh/manual/olares/wise/subscribe.md new file mode 100644 index 000000000..653d8dc2b --- /dev/null +++ b/docs/zh/manual/olares/wise/subscribe.md @@ -0,0 +1,86 @@ +--- +outline: [2, 3] +description: 了解如何在 Wise 中添加和管理 RSS 订阅、使用 OPML 导入订阅源，以及上传 Cookie 改善阅读体验。 +--- + +# 订阅和管理订阅源 +Wise 提供灵活的订阅选项，帮助你关注喜爱的内容来源，包括文章、博客、播客和视频频道。本指南说明如何添加和管理你的订阅。 + +## 订阅方法 +:::tip 提示 +当你在 Wise 中订阅播客或视频频道时，新剧集会自动下载到你的 Olares 存储中。这确保了你即使离线也可以随时随地可以访问媒体内容，无须受到文件来源删除不可用的影响。 +::: + +### 从推荐内容页面订阅 +在**为你推荐**页面浏览推荐内容时，可以通过以下方式订阅内容源： + +* 点击**信息**栏中的**订阅源**。 +* 点击工具栏中的 bookmark_add。 + +### 手动添加 RSS 订阅源 + +1. 使用以下任一选项打开 RSS 订阅对话框： + * 在左侧菜单栏中，点击 add_circle，选择 **RSS 源**。 + * 在左侧菜单栏中，点击 settings，选择 **RSS 订阅源**，然后在页面右上角点击**添加源**。 +2. 在对话框中，使用以下格式之一输入订阅源信息： + * 订阅源名称。例如：`36kr`。 + * 支持将内容生成 RSS 订阅源的网站 URL。 + * 可用的 RSS 链接。 +3. 点击**添加**完成订阅。 + +### 导入 OPML 订阅源 +OPML 文件可以让你轻松导入其他用户分享的 RSS 订阅源，或从其他 RSS 阅读器迁移订阅内容。 + +1. 左下角点击 settings，选择**偏好设置**。 +2. 在**导入/导出**下，点击**从 OPML 文件导入订阅源**。 +3. 选择 OPML 文件并打开。 + +导入完成后，你可以在 settings > **RSS 订阅源**中查看和管理这些订阅。 + +:::info +导入时只会添加新的订阅源，不会导入原 RSS 阅读器中的历史内容。 +::: +### 使用 LarePass 订阅网页内容 +:::tip 提示 +LarePass 扩展目前仅支持 Chrome 浏览器。请从 [LarePass 页面](https://olares.cn/larepass)下载。 +::: + +1. 打开 LarePass 浏览器扩展，点击**收集**。 +2. 在 **RSS** 部分查看当前网页可用的订阅源。 + :::info + 只有当前页面检测到订阅源时，**RSS** 选项才会出现。 + ::: +3. 点击 bookmark_add 将订阅源添加到 Wise。 + +:::tip 上传 Cookie + +某些网站需要 Cookie 才能访问内容。你也可以通过上传 Cookie 提升网站的访问体验。要上传网站的 Cookie： +1. 登录目标网站。 +2. 打开 LarePass 浏览器扩展，点击**收集** > **Cookie**。 +3. 点击**上传**应用更改或启用**自动同步**。 + +鼠标悬停 Cookie 查看详细信息。 +::: +## 查看订阅列表 + +从settings > **RSS 订阅源**页面访问你所有的 RSS 订阅源。 + +你可以： + +* 查看订阅源详情和描述。 +* 搜索特定订阅源。 +* 复制 RSS 链接。 +* 编辑订阅源名称和描述。 + +## 取消订阅 + +:::warning 警告 +取消订阅将删除该订阅源的所有文章，除非它们已保存到库中。此操作不可撤销。 +::: + +你可以通过以下方式取消订阅内容源： + +* 从**信息**栏取消订阅。 +* 通过阅读页面工具栏。 +* 使用 LarePass 浏览器扩展。 +* 在 **RSS 订阅管理**页面取消订阅。 \ No newline at end of file diff --git a/docs/zh/manual/release-notes.md b/docs/zh/manual/release-notes.md new file mode 100644 index 000000000..c5443e323 --- /dev/null +++ b/docs/zh/manual/release-notes.md @@ -0,0 +1,3 @@ +# Release notes + +Text diff --git a/docs/zh/manual/system-architecture.md b/docs/zh/manual/system-architecture.md new file mode 100644 index 000000000..16028e608 --- /dev/null +++ b/docs/zh/manual/system-architecture.md @@ -0,0 +1,220 @@ +--- +outline: [2, 3] +description: 全面了解 Olares 架构，涵盖基础设施、平台服务和应用框架。 +--- + +# Olares 架构 + +本文详细介绍了 Olares 的架构，阐述了各层及其组件的用途和功能。 + +![Olares 架构图](/images/manual/architecture-diagram.png) + +## 基础设施 + +基础设施层提供了容器编排、存储、网络和集群管理等核心基础服务。 + +### 容器编排 + +Olares 根据底层环境支持不同的 Kubernetes 发行版： +- Linux 环境（包括 WSL、PVE、LXC、树莓派）：用户可以选择安装 [Kubernetes](https://kubernetes.io/) 或轻量级的 [K3s](https://k3s.io/)。K3s 作为默认选项，在本地硬件上能提供更好的性能和资源效率。 +- macOS：使用 [minikube](https://minikube.sigs.k8s.io/) 在 Linux 虚拟机中部署 Kubernetes，确保跨平台的统一体验。 + +无论选择哪种 Kubernetes 发行版，用户都能获得一致的 Olares 核心能力和使用体验。 + +### 网络 + +网络组件确保容器、节点和服务之间的无缝通信，包括： + +- [CoreDNS](https://coredns.io/)：为集群提供 DNS 服务，实现高效的域名解析。 +- [Calico](https://www.tigera.io/project-calico/)：提供高性能容器网络接口（CNI），负责容器和虚拟机之间的通信，并提供高级网络策略控制。 +- [Envoy](https://www.envoyproxy.io/)：高性能、可扩展的边缘和服务代理。Envoy 作为服务间通信的中间件，处理负载均衡、服务发现、安全通信和可观测性。它可以作为独立的反向代理或 API 网关使用，也常作为服务网格（Service Mesh）的数据平面组件。 + +这些组件共同确保了 Olares 中网络的健壮性、可扩展性和安全性。 + +### 分布式存储 + +Olares 为单节点和多节点设置提供灵活的存储方案： + +- 本地存储：适用于单节点部署，提供最佳读写性能。 +- [S3](https://aws.amazon.com/s3/)：云存储选项，适合通过 S3 或任何兼容 S3 的服务进行云部署。 +- [MinIO](https://min.io/)：自托管部署的分布式存储解决方案。用户可以通过 Olares 搭建 MinIO 集群，或挂载现有的 MinIO 集群。 + +这种方案确保了应用能够访问所需的存储机制，无论是本地还是分布式环境。 + +### 分布式键值存储 + +Olares 使用 [etcd](https://etcd.io/) 作为分布式键值存储。etcd 是存储和管理 Kubernetes 集群数据的核心组件。 + +### GPU 管理 + +Olares 利用 CUDA 驱动、NVIDIA 设备插件和 nvshare 等组件协同工作，有效管理和分配 GPU 资源： + +- CUDA：作为 GPU 硬件和操作系统之间的核心接口。 +- NVIDIA 设备插件：使 GPU 资源能够被容器或 Pod 发现、调度和分配。 +- [nvshare](https://github.com/grgalex/nvshare)：允许多个容器或 Pod 共享单个 GPU，实现 GPU 的共享和独占使用，提高 GPU 利用率。 + +:::info 注意 +Olares 目前的 GPU 管理功能仅支持单节点单 GPU 的部署场景。 +::: +从 Olares v1.11 开始，支持 [CUDA](https://developer.nvidia.com/cuda-toolkit)（12.4 及以上版本）。当宿主机环境的 CUDA 配置变更时，可以通过 `olares-cli` 通知 Olares 集群进行配置。 + +### 容器管理 +Olares 使用轻量级容器运行时 [containerd](../developer/install/installation-overview.md#容器运行时containerd) 进行容器化部署。 + +### Olares Controller Panel + +Olares 的集群管理通过以下工具实现： + +- [olares-cli](../developer/install/cli/olares-cli.md)：命令行工具，用于管理 Olares 集群、应用和硬件节点等。 +- [olaresd](../developer/install/installation-overview.md#系统守护进程olaresd)：Olares 的守护进程，用于监控硬件和网络变更、处理集群升级和重启等。 + +这些工具简化了 Olares 的安装、维护和扩展过程。 + +## 平台层 + +平台层的服务运行在容器中，提供数据库、消息系统、文件系统、工作流编排、密钥管理和可观测性等中间件服务。 + +### 关系型数据库 + +Olares 使用 [PostgreSQL](https://www.postgresql.org/) 16 作为主要关系型数据库。所有应用共享一个 PostgreSQL 实例，每个应用都有专用账号以实现隔离。PostgreSQL 同时作为全文搜索引擎和向量数据库。 + +多节点方面，使用 [Citus](https://github.com/citusdata/citus) 实现，但该方案仍在调试中。 + +未来，PostgreSQL 预计会迁移到基础设施层以实现更好的资源管理。 + +### 键值缓存 + +Olares 集成了 [KVRocks](https://github.com/apache/incubator-kvrocks)，这是一个基于 RocksDB 构建的 Redis 兼容持久化键值存储。KVRocks 在内存和磁盘存储之间取得平衡，比 Redis 集群更节省资源，但性能略有损失。 + +### 消息队列 + +使用轻量级高性能的 [NATS](https://nats.io/) 作为消息系统，这是一个轻量级、高性能的面向消息的中间件。NATS 在保证可靠消息队列的同时，确保较低的资源消耗。 + +### 分布式文件系统 + +Olares 采用云原生分布式文件系统 [JuiceFS](https://juicefs.com/)，为应用提供 POSIX 兼容接口。当使用 S3 或 MinIO 作为存储后端时，JuiceFS 确保跨节点的无缝文件访问。 + +### 工作流管理 + +Olares 使用 [Argo Workflows](https://argoproj.github.io/) 进行工作流编排。这个 Kubernetes 原生工具可以自动化复杂任务流程，如 Olares 分布式推荐引擎所需的任务。目前这个功能尚未对第三方应用开放。 + +### 密钥管理 + +Olares 集成了两个密钥管理解决方案： + +- [Vault](https://github.com/beclab/olares/tree/main/apps/vault)：保护账号、密码和助记词等敏感数据。它对密钥进行加密，即使服务器被攻破，数据也能保持安全。Vault 由 Olares 团队基于 [Padloc](https://padloc.app/) 开发。 +- [Infisical](https://infisical.com/)：用于管理敏感信息和防止 Olares 开发中的密钥泄露。 + +### 可观测性 + +Olares 通过以下组件提供可观测性： + +- [Prometheus](https://prometheus.io/)：用于系统监控和资源使用跟踪。它为**仪表盘**和**应用市场**等应用提供资源使用方面的数据。 +- [OpenTelemetry](https://opentelemetry.io/)\*：使用基于 eBPF 的监控，实现 Olares 系统内请求工作流的追踪。*（开发中）* + +### 其他中间件 + +Olares 在**应用市场**中集成了一些常用中间件，如用于可视化的 [Grafana](https://grafana.com/)、用于文档存储的 [MongoDB](https://www.mongodb.com/) 和用于混沌测试的 [Chaos Mesh](https://chaos-mesh.org/)。 + +## 应用框架 + +应用框架层为系统和第三方应用提供通用功能和接口。 + +### 认证与授权 + +Olares 使用 [LLDAP](https://lldap.example.com/) 管理用户账号并为应用提供 LDAP（轻量目录访问协议）服务。 + +此外，[Authelia](https://www.authelia.com/) 添加了认证和授权支持，包括多因素认证和单点登录（SSO）。 + +### 应用治理 + +应用治理的组件包括： +- [app-service](https://github.com/beclab/app-service)：处理应用生命周期管理和资源分配。 +- [system-server](https://github.com/beclab/system-server)：管理应用间接口调用的权限，以及应用和数据库中间件之间的网络路由。 +- image-server：与 app-service 协作管理 Olares 应用所需的容器镜像。 +- [bfl](https://github.com/beclab/bfl)：聚合后端接口，代理所有系统服务的请求，如用户隔离的系统信息和集群信息。 + +### 网络连接 +Olares 通过以下方式提供安全灵活的网络连接： +- 反向代理：Olares 支持 [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/)、Olares Tunnel 和自建 FRP 三种方案。 +- [Tailscale](https://tailscale.com/)：让用户可以从任何地方安全访问系统。 +- [Headscale](https://github.com/juanfont/headscale)：Tailscale 控制面板的自托管实现。 + +### 文件服务 +文件服务的组件包括： +- File server：提供基本的文件管理服务。 +- [Seafile](https://www.seafile.com/)：Dropbox 的开源替代品，用于文件同步。Olares 深度集成了 Seafile，使用户能将分散在多个设备上的文件同步到统一的存储库中。 +- Drive server：提供与 Google Drive、Dropbox 和 S3 等外部存储服务的接入。 +- Media server：使用 [ffmpeg](https://github.com/FFmpeg/FFmpeg) 流式传输视频文件。 + +### 知识服务 +知识服务的组件包括： +- Knowledge：存储用户通过浏览器扩展收集或通过 LarePass 从手机分享的网页、视频、音频、PDF 和 EPUB 等内容。这个存储库也被分布式推荐引擎用来存储其推荐的结果。 +- Download：使用 [aria2](https://aria2.github.io/) 和 [youtube-dlp](https://github.com/yt-dlp/yt-dlp) 下载文件、磁力链接和在线视频。 +- Search：为 Knowledge 和**文件管理器**的内容提供全文搜索。 +- [RSSHub](https://github.com/DIYgod/RSSHub)：生成 RSS 源以便订阅内容。 + +### AI 服务 + +Olares 提供以下 AI 能力： +- 模型服务*：提供模型托管服务。*（开发中）* +- RAG 接口*：为文件、文章、图片和视频提供检索增强生成（RAG）服务。*（开发中）* +- Agent 和工作流编排*：管理 Agent 和工具工作流。*（开发中）* + +### 系统服务 + +系统服务包括： +- 通知：传递系统级通知。 +- 备份*：支持目录、应用和集群备份。*（开发中）* +- 升级*：支持系统自动升级。*（开发中）* + +## 系统应用 + +Olares 预装了用于管理文件、知识、密码和系统本身的应用。 + +用户可以通过应用市场安装更多应用。 + +### 文件管理器 + +文件管理应用，管理和同步跨设备和不同来源的文件，实现无缝共享和访问。 + +### Wise + +本地优先、AI 原生的现代阅读器，帮助从各平台收集、阅读和管理信息。用户可以运行自托管的推荐算法来过滤和排序在线内容。 + +### Vault + +安全的密码管理器，用于存储敏感信息并在设备间同步。 + +### 应用市场 + +去中心化、无许可的应用商店，用于安装、卸载和更新应用或推荐算法。 + +### 桌面 + +用于管理和访问已安装应用的枢纽，也支持搜索文件和应用。 + +### Profile + +用于个性化个人主页。 + +### 设置 + +系统配置应用。 + +### 仪表盘 + +监控系统资源使用的应用。 + +### 控制面板 + +Olares 的控制台，提供对系统及其环境的精确和自主控制。 + +### DevBox + +用于构建和部署 Olares 应用的开发工具。 + +## 了解更多 +- 要开始使用 Olares，请参阅[快速开始](get-started/index.md)。 +- 要深入了解 Olares 的内部原理，请参阅[概念](concepts/index.md)中的主题。 +- 要详细了解 Olares 中各组件如何被编排，请参阅 [Olares 安装概述](../developer/install/index.md)。 \ No newline at end of file diff --git a/docs/zh/manual/what-is-olares.md b/docs/zh/manual/what-is-olares.md new file mode 100644 index 000000000..52315a8e4 --- /dev/null +++ b/docs/zh/manual/what-is-olares.md @@ -0,0 +1,14 @@ +# 什么是 Olares + +Olares 是一个让你完全掌控的主权云平台。它是公有云（如 AWS）的开源、自托管替代方案，旨在帮助你重获数据主权和隐私控制权。通过将 Kubernetes 的强大功能与简洁的界面相结合，Olares 使你能够完全掌控自己的数据和计算资源。无论你是在管理家庭实验室、部署应用程序，还是保护个人隐私，Olares 都能提供媲美公有云的灵活性和功能，同时确保隐私和安全不受损害。 + +## Olares 能做什么 +Olares 的典型应用场景包括： + +- 🖥️ **家庭实验室服务器**：将你的个人设备转变为功能丰富的家庭实验室，用于容器化应用实验、本地 AI 模型运行、自托管服务管理或云技术测试——这一切都在你自己的私有基础设施中进行。 +- 🤖 **本地人工智能**：在你的设备上直接托管和运行最新的开源 AI 模型，包括大型语言模型、图像生成和语音识别。构建可以与你的数据和应用程序集成的自定义 AI 助手，同时保持所有内容的私密性和安全性。 +- 💻 **个人数据仓库**：安全地存储、同步和管理你的照片、文档和重要文件，将它们统一存放在一个可以随时随地访问的私有存储系统中。 +- 🛠️ **自托管工作空间**：为你的团队或家庭创建一个免费的协作工作空间，使用开源替代方案取代商业生产力工具。 +- 🎥 **私人媒体服务器**：将你的个人媒体收藏转变为专属流媒体服务，完全由你的设备托管。 +- 🏡 **智能家居**：将 Olares 用作管理物联网设备和家庭自动化的中枢控制点。 +- 🤝 **去中心化社交媒体**：托管去中心化社交媒体平台，如 Mastodon、Ghost 或 WordPress，无需担心被封号或平台费用，轻松打造个人品牌。 \ No newline at end of file diff --git a/docs/zh/space/backup-restore.md b/docs/zh/space/backup-restore.md new file mode 100644 index 000000000..dfd0d8fc9 --- /dev/null +++ b/docs/zh/space/backup-restore.md @@ -0,0 +1,52 @@ +--- +description: 介绍 Olares Space 的数据备份工具，支持查看备份记录、管理系统快照、恢复云端数据。 +--- +# 备份与恢复 + +Olares Space 是为 Olares 实例提供快照备份的官方解决方案。你可以随时将 Olares 恢复到最近的状态。本节介绍如何在 Olares Space 中管理备份和恢复操作。 + +:::info 注意 +每个 Olares 实例可以获得 10GB 的免费备份空间。超出部分将按照云服务商的定价收费。 +::: + +## 查看备份列表 + +备份任务列表显示每个备份任务的信息，包括： + +- 初始创建时间 +- 最近快照时间 +- 总体存储用量 + +![alt text](/images/how-to/space/backup_list.jpg#bordered) + +点击任务的**查看详情**可以进入详情页面。详情页面展示了该任务创建以来的存储用量变化，以及所有成功的快照记录。 + +:::info 注意 +目前仅支持从最近一次快照恢复。 +::: + +## 将备份恢复至 Olares Space + +![alt text](/images/how-to/space/restore_backup_to_the_olares_space.jpg#bordered) + +将快照恢复到云端的操作流程与新建云端 Olares 类似。 + +1. 设置相关信息。 + + a. 选择云服务商和数据中心位置。 + + b. 选择实例的硬件配置。 + + c. 确认快照信息并输入备份密码。 + +2. 了解存储和带宽费用。
每个实例都包含一定额度的免费存储和流量配额。超出部分将产生费用。 + +3. 确认订单并完成支付。之后 Olares 开始安装。 + +:::info 注意 +在安装过程中，Olares 会验证备份密码。如果密码不正确，系统会要求重新输入正确的密码。如果忘记了备份密码，将无法继续恢复流程。此时请销毁实例，重新进行恢复。 +::: + +:::info 注意 +为避免冲突或其他意外问题，在恢复到云端 Olares 之前，必须先销毁使用相同名称的现有 Olares。 +::: \ No newline at end of file diff --git a/docs/zh/space/billing.md b/docs/zh/space/billing.md new file mode 100644 index 000000000..da3b9335a --- /dev/null +++ b/docs/zh/space/billing.md @@ -0,0 +1,60 @@ +--- +description: 说明 Olares Space 的收费项目和计费规则，包含账单周期、付费方式、优惠政策。 +--- +# 计费说明 + +Olares 与 Stripe 合作提供安全的支付服务。系统会通过邮件发送账单和收据，方便你进行记录和分析。如果在支付过程中遇到问题，请联系客服。 + +## 计费范围 + +以下服务或产品需要付费： + +- **托管版 Olares**：在 AWS 或 GCS 等云服务商上部署 Olares 的预付费产品。具体价格取决于所选云服务商。 +- **主机实例流量**：指定区域外的云主机对外流量产生的后付费费用。 +- **工作节点实例**：向托管版 Olares 添加工作节点会产生月度费用。该费用将计入每月账单。 +- **云存储**：通过 JuiceFS 存储系统数据的后付费产品。根据使用量在结算周期结束时收费。 +- **云备份/恢复**：将主机数据备份到公共存储的服务。根据使用量在结算周期结束时收费。 +- **Cloudflare Tunnel（FRP）流量**：自托管 Olares 通过公共链接访问服务时产生的后付费流量费用。 +- **GPU 单元**：GPU 相关服务的预付费产品。根据使用情况从预付费单元中扣除费用。 + +### 账单生成和付费场景 + +以下操作会生成账单： + +- **在云端创建 Olares**：选择云服务商和配置后立即生成账单。必须完成支付才能开始安装。 +- **添加/移除工作节点**：添加工作节点时根据计费周期的剩余时间生成账单。移除工作节点时同样会计算退款金额。 +- **恢复快照**：相当于创建新的 Olares，需支付月度费用。 +- **销毁 Olares**：计算销毁日期前的费用。如适用则处理退款。 + +月度账单每月更新一次，包括基础订阅费以及当月产生的其他费用，如添加工作节点、额外流量和存储费用等。 + +## 月度扣费方式 + +Olares 采用月度计费周期： +- **自动扣费**：首次付款时将授权自动扣费，第一次使用的支付方式将设为默认方式。如果你倾向于手动支付，可以在控制面板中关闭自动扣费，但请确保按时结清账单以避免服务中断。 +- **支付有效期**：每次购买生成的账单有效期为 24 小时。 + +## 使用优惠额度或优惠券 + +我们会通过促销活动发放试用额度或优惠券。 + +- 获得试用额度后，可以在**计费** > **余额记录**中查看，并在支付时直接用于特定产品。 +- 获得促销优惠码后，可以在**计费** > **优惠券**中兑换。可用于计划折扣、计划订阅、Olares 会员等。 + +::: info 注意 +试用额度或优惠券不可退款。如果申请退款，系统只会退还实际支付的金额。 +::: + +## 常见问题 + +### 别人访问部署在 Olares 上的 WordPress 站点时，我会产生费用吗？ + +会的，Cloudflare FRP Tunnel 的流量会产生 Cloudflare 费用。这主要用于隐藏 Olares 的真实 IP，并提供防御分布式拒绝服务（DDoS）等威胁的安全保护。如果你在云端托管 Olares，还会产生所选云服务商的流量费用。 + +### 账单金额不足 1 美元会怎样？ + +如果总账单金额不足 1 美元，系统不会产生扣费。该金额会计入余额，并累计到下期账单中。 + +### 如何处理负余额？ + +出现负余额并不一定意味着欠费。如果看到负余额，请在**计费** > **余额**中查看详情。请及时支付未结清的金额，以免服务中断。 \ No newline at end of file diff --git a/docs/zh/space/create-olares.md b/docs/zh/space/create-olares.md new file mode 100644 index 000000000..8f8533fb2 --- /dev/null +++ b/docs/zh/space/create-olares.md @@ -0,0 +1,90 @@ +--- +outline: [2, 3] +description: 在云端创建 Olares 实例的操作指南，涵盖环境设置、资源配置、安装进度查看和系统激活步骤，帮助快速部署并开始使用。 +--- + +# 创建云端 Olares + +云端 Olares 提供了便捷的部署方式，让你无需直接管理硬件即可搭建 Olares 环境。 +本节将为你详细介绍如何创建和管理云端 Olares。 + +::: info 注意 +- **托管服务**目前处于邀请制测试阶段。如需使用云端 Olares，请联系我们获取邀请。 +- 如果你想了解如何搭建自托管 Olares，请参考[快速入门指南](../manual/get-started/index.md)。 +::: + +## 准备工作 + +确保你已有 Olares ID，用于登录 Olares Space 并激活 Olares 实例。 + +## 创建 Olares + +1. 使用 LarePass 扫描二维码登录 [Olares Space](https://space.olares.com/)。 +2. 进入**集群**页面，选择第二个选项开始创建。 + + ![基础配置](/images/how-to/space/basic_configuration.jpg#bordered) +3. 配置安装环境： + + a. 选择云服务提供商和离用户或工作负载最近的数据中心位置。 + + b. 选择实例的 CPU、内存和存储资源。 + + c. 选择合适的 Olares 版本和要安装的 Kubernetes/K3S 方案。 + + :::tip 托管大语言模型 + 如果你打算托管大语言模型（LLM），请选择**阿里云香港**地区，目前只有该地区提供共享 GPU 服务的实例。 + ::: + +4. 查看存储和流量费用。 + + ![存储和网络费用](/images/how-to/space/storage_and_network.jpg#bordered) + + ::: tip 额外费用 + 每个实例都包含一定额度的免费存储和带宽。超出这些配额的使用量将按照云服务商的定价收取额外费用。 + ::: +5. 确认订单详情，包括实例配置、选项和费用。 +6. 完成支付以启动安装流程。 + +## 监控安装进度 + +云端 Olares 的创建和安装通常需要约 10 分钟。在此期间，你可以实时监控进度和查看日志。 + +### 系统状态 + +安装过程包含几个关键阶段，对应不同状态： + +| 状态 | 说明 | +|----------|----------------------| +| **未支付** | 实例已创建但待支付，可以取消。 | +| **获取中** | 支付确认，系统正在创建资源。 | +| **排队中** | 已提交资源创建请求。 | +| **等待中** | 资源已创建，等待安装操作系统。 | +| **安装中** | 正在安装操作系统。 | +| **恢复中** | 正在从备份恢复操作系统。 | +| **恢复错误** | 由于快照密码错误导致恢复失败。 | +| **重启中** | 系统正在重启。 | +| **停止中** | 系统正在关机。 | +| **启动中** | 系统正在启动。 | +| **运行中** | 系统正常运行，可以重启、停止或销毁实例。 | +| **已停止** | 系统未运行，可以重启或销毁实例。 | +| **错误** | 资源创建或安装过程中遇到错误。 | +| **销毁中** | 正在销毁实例。 | +| **已销毁** | 实例已被销毁。 | +| **已取消** | 实例因取消或支付问题而终止。 | +| **待激活** | 系统等待激活，激活后将开始运行。 | + +### 实时日志 + +点击**日志**可查看详细日志，实时了解安装进度。 + +## 激活 Olares + +当安装进入**待激活**状态时，按以下步骤激活 Olares： + +1. 点击**激活**。弹窗将显示 Olares ID、一次性密码和向导 URL。 + + ![一次性密码](/images/how-to/space/one_time_password.jpg#bordered) + +2. 在浏览器中打开向导 URL，使用一次性密码首次登录 Olares。 +3. 根据提示通过 LarePass 修改 Olares 密码。 +4. 按照屏幕指引完成剩余激活步骤。 \ No newline at end of file diff --git a/docs/zh/space/host-domain.md b/docs/zh/space/host-domain.md new file mode 100644 index 000000000..dc52b3825 --- /dev/null +++ b/docs/zh/space/host-domain.md @@ -0,0 +1,80 @@ +--- +outline: [2, 3] +description: 介绍在 Olares Space 中添加自定义域名的步骤，包含域名验证方法、DNS 解析配置、组织 ID 创建和邮箱关联流程。 +--- + +# 配置自定义域名 + +无论是企业用户希望员工使用公司特定域名登录，还是个人想使用自己的域名，Olares Space 都支持设置自定义域名以便访问。 + +本指南将帮助你在 Olares Space 上为 Olares 系统添加自己的域名。 + +## 前提条件 + +::: info 注意 +只有账户处于 DID 阶段时才能绑定新域名。如果账户已经绑定了 Olares ID，说明该账户已经关联了一个域名。 +::: + +在创建和配置自定义域名之前，请确保： + +- **DID 账户状态**：确认账户处于 DID 状态（即尚未绑定 Olares ID）。 + +- **域名**：通过域名注册商注册了域名。该域名不能已经绑定在 Olares Space 的其他账户上。 + +- **LarePass 移动端**：安装了 LarePass 移动端，因为可验证凭证和域名管理任务需要使用此应用。 + +- **域名 DNS 设置权限**：可以配置 TXT 记录和 NS 记录。 + +## 添加域名 + +准备就绪后，按照以下步骤在 Olares Space 中添加域名。 + +1. 在 Olares Space 控制台中，进入**域名** > **域名设置**，按照提示输入你的自定义域名。 + + ![alt text](/images/how-to/space/submit_a_domain.jpg#bordered) + +2. 为域名添加 TXT 记录以验证域名所有权。系统会验证你的配置。验证通过后，域名设置状态会自动更新为**等待配置域名 NS 记录**。 + + ![alt text](/images/how-to/space/txt.jpg#bordered) + +3. 添加 NS 记录，允许 Olares Space 为你的域名配置 DNS。 + + ![alt text](/images/how-to/space/ns.jpg#bordered) + + 系统会验证你的配置。验证通过后，域名状态会更新为**等待申请域名可验证凭证**。 + + ![alt text](/images/how-to/space/awaiting_domain.jpg) + +4. 打开 LarePass 移动端，进入**组织 Olares ID** > **创建组织**。你应该能看到你的域名。 + +5. 点击域名将其存储在区块链上。完成后，Olares Space 上的域名设置状态应变为**等待配置规则**。 + +至此，你已经成功将域名与 DID 关联。现在可以继续[设置邮件邀请规则](manage-domain.md#设置邮箱邀请规则)并使用该域名创建组织 Olares ID。 + +## 创建组织 Olares ID + +现在你的组织已有经过验证的域名，你或被邀请的其他成员可以使用这个域名创建 Olares ID。 + +![org-olares-id](/images/how-to/larepass/organization_olares_id.png) + +1. 在 LarePass 移动端，进入**组织 Olares ID** > **加入已有组织** +2. 输入你的组织域名，点击**继续**。如果出现错误，请检查域名是否已验证和配置 +3. 通过邮箱账号绑定 VC。目前仅支持 Gmail 和 Google Workspace 邮箱 + +完成后，你将获得组织 Olares ID。现在可以继续[激活 Olares](/manual/get-started/activate-olares)。 + +## 域名状态说明 + +提交域名后，需要完成几个步骤来验证输入的域名。 + +下表说明了不同的域名状态及相应需要执行的操作： + +| 状态 | 需执行的操作 | +|-------------|------------------------| +| 等待配置 TXT 记录 | 添加 TXT 记录 | +| 等待配置 NS 记录 | 添加 NS 记录 | +| 等待申请域名可验证凭证 | 在移动端完成区块链域名申请 | +| 等待提交域名可验证呈现 | 在移动端完成区块链域名申请 | +| 等待配置规则 | 为组织成员设置邮件邀请规则 | +| 绑定中 | 等待与 Olares 绑定，可以访问详情页面 | +| 已分配 | 已绑定 Olares，可以访问详情页面 | \ No newline at end of file diff --git a/docs/zh/space/index.md b/docs/zh/space/index.md new file mode 100644 index 000000000..da2a6c9c7 --- /dev/null +++ b/docs/zh/space/index.md @@ -0,0 +1,23 @@ +--- +description: Olares Space 是 Olares 在公有云上的全托管服务，支持数据备份、域名配置、反向代理和 GPU 资源管理，通过 LarePass 扫码登录以访问所有功能。 +--- +# Olares Space 概述 + +Olares Space 是 Olares 在公有云上的全托管服务，提供两大类服务： + +- **基础设施服务**：负责数据备份、自定义域名配置、反向代理和共享 GPU 资源管理 +- **托管服务**：在公有云平台上托管和管理 Olares 实例 + +Olares Space 账号与你的 Olares ID 或 DID 关联。你可以通过 LarePass 扫描二维码登录 Olares Space。 + +本章节将为你介绍 Olares Space 的使用方法，包括： + +- [登录和退出 Olares Space](manage-accounts.md) +- [托管 Olares](create-olares.md) +- [管理 Olares](manage-olares.md) +- [托管自定义域名](host-domain.md) +- [管理组织域名](manage-domain.md) +- [备份和恢复 Olares](backup-restore.md) +- [使用量和计费](billing.md) + + diff --git a/docs/zh/space/manage-accounts.md b/docs/zh/space/manage-accounts.md new file mode 100644 index 000000000..35ba206f2 --- /dev/null +++ b/docs/zh/space/manage-accounts.md @@ -0,0 +1,44 @@ +--- +description: 介绍 Olares Space 的账号操作方法，通过 LarePass 扫码实现 DID 和 Olares ID 登录，支持多账号导入和切换，可随时退出登录切换身份。 +--- +# 管理 Olares Space 账号 + +本指南将介绍 Olares Space 的常见账号操作，包括登录、多账号管理和退出登录。 + +## 登录 Olares Space + +Olares Space 使用去中心化身份（DID）或 Olares ID 进行身份验证。请确保你已在 LarePass 中获取了相应的凭据。 + +1. 在 LarePass 应用中，选择要用于登录的 DID 或 Olares ID。 +2. 在浏览器中打开 [https://space.olares.com/](https://space.olares.com/)。 +3. 使用 LarePass 扫描二维码。 + +::: tip DID 与 Olares ID 的差异 +根据使用 DID 还是 Olares ID 登录，Olares Space 提供的功能和服务会有所不同。 +- **使用 DID 登录**：由于账号未关联域名，你可以设置自己的域名。但在激活 Olares 设备前，必须先将 DID 绑定到 Olares ID。 +- **使用 Olares ID 登录**：只要该名称尚未被其他 Olares 设备使用，你就可以创建 Olares。但因为 Olares ID 已对应唯一域名，所以无法使用自定义域名。 + ::: + +## 退出登录 + +退出账号有以下方式： + +1. 点击右上角的头像。 +2. 选择**退出登录**。 + +或者： + +1. 从菜单中选择**切换账号**。 +2. 点击任意列出账号旁边的 logout 图标。 + +## 管理多个账号 + +每个 Olares ID 只能关联一个 Olares。通过 Olares Space 的多账号管理功能，你可以轻松切换账号，方便管理多个 Olares ID 和实例。 + +添加账号的步骤： + +1. 点击右上角的头像。 +2. 在弹出菜单中选择**导入账号**。 +3. 打开 LarePass，扫描二维码登录。 + +添加多个账号后，可以通过菜单中的**切换账号**选项进行切换。如果账号已退出登录，系统会跳转到二维码登录页面。 \ No newline at end of file diff --git a/docs/zh/space/manage-domain.md b/docs/zh/space/manage-domain.md new file mode 100644 index 000000000..18f02590f --- /dev/null +++ b/docs/zh/space/manage-domain.md @@ -0,0 +1,41 @@ +--- +outline: [2, 3] +description: 讲解 Olares Space 的域名管理功能，包含邮箱邀请规则配置、成员添加和移除操作，可选择固定邮箱后缀或指定地址两种方式。 +--- + +# 管理域名 + +在进行管理之前，你需要先[添加域名](host-domain.md#添加域名)。完成域名设置后，你可以配置组织成员的邮箱邀请规则，并通过邮件邀请他们创建属于组织的 Olares ID。 + +## 设置邮箱邀请规则 + +大多数企业都会为团队成员使用统一的域名后缀，比如 A 的邮箱是 `A@myteam.com`，B 的邮箱是 `B@myteam.com`。不过有时团队成员可能会使用不同域名的邮箱。为了适应这些场景，Olares 提供了两种添加组织成员邮箱的规则： + +![alt text](/images/how-to/space/set_rule.jpg#bordered) + +- **固定邮箱后缀**：适用于所有团队成员使用相同邮箱域名的情况。输入组织的域名后缀（如：`@company.com`），任何匹配该后缀的邮箱都可以关联到组织的 Olares ID。 + +- **指定邮箱地址**：适用于组织没有统一企业邮箱后缀的情况。需要手动添加组织每个成员的邮箱地址。 + +:::info 注意 +- 目前两种规则都仅支持 Gmail。 +- 已用于创建组织 Olares ID 的邮箱会显示在成员列表中，且无法删除。 +- 手动添加但尚未用于创建 Olares ID 的邮箱会显示为“未绑定”状态，可以删除。 + ::: + +## 成员管理 + +设置邮箱规则后，你可以在组织下添加或删除成员。 + +![alt text](/images/how-to/space/management_members.jpg#bordered) + +### 添加成员 + +添加成员的步骤： + +1. 在域名管理页面，通过输入邮箱地址将成员添加到组织。 +2. 通知相关用户使用其邮箱地址[创建组织 Olares ID](host-domain.md#创建组织-olares-id)。 + +### 删除成员 + +你可以删除尚未用于创建 Olares ID 的邮箱地址。一旦邮箱与组织的 Olares ID 关联，就无法删除。 \ No newline at end of file diff --git a/docs/zh/space/manage-olares.md b/docs/zh/space/manage-olares.md new file mode 100644 index 000000000..222f3272c --- /dev/null +++ b/docs/zh/space/manage-olares.md @@ -0,0 +1,52 @@ +--- +outline: [2, 3] +description: 介绍云端 Olares 实例的管理功能，包含系统监控面板、工作节点添加方法和共享 GPU 使用方案，助力提升系统运行效率。 +--- + +# 管理 Olares + +本页介绍如何在 Olares Space 中管理 Olares，包括监控系统数据、添加工作节点和管理云服务。 + +## 查看系统状态 + +你可以通过 **Olares Space** 监控 Olares 的系统状态： + +1. 在 LarePass 应用中，进入**设置** > **集成**。 +2. 点击右上角的 add，将 Olares Space 账号与 Olares 设备关联，授权 Olares Space 访问系统数据。 +3. 登录 [**Olares Space**](https://space.olares.com/)。 +4. 在 **Olares** 页面的系统面板中查看**存储使用量**和**流量消耗**。 + +![系统面板](/images/how-to/space/my_olares.jpg#bordered) + +:::info 注意 +对于自托管 Olares 用户，请重点关注内网穿透服务的**流量统计**和备份服务的**存储使用量**。这些服务可能会根据使用情况产生费用。 +::: + +## 添加工作节点 + +云端 Olares 用户可以通过添加工作节点来提升性能： + +1. 点击右上角的 more_horiz，选择**添加工作节点**。 +2. 在引导页面选择所需的硬件配置。 +3. 查看存储和流量费用。 +4. 确认订单并提交。 + +## 销毁 Olares + +如果不再需要 Olares 服务，可以按以下步骤销毁实例： + +1. 点击右上角的 more_horiz。 +2. 选择**销毁 Olares**。 +3. 确认操作并结算使用费用： + - 如果符合退款条件，退款金额将返还到账户余额 + - 如需补充支付，请确认并完成支付 + +## 共享 GPU 方案 + +目前我们不提供包含 GPU 的云实例。不过，对于需要 GPU 功能的用户，我们通过 rCuda 提供共享 GPU 方案。这个方案特别适合 Stable Diffusion 等应用，每张图片的成本约为 0.02 美元。 + +::: info 注意 +对于大语言模型（LLM），共享 GPU 方案仍在开发中，可能需要进一步优化。 +::: + +如果你需要 GPU 支持，请通过 [Discord](https://discord.com/invite/BzfqrgQPDK) 联系我们。 \ No newline at end of file diff --git a/docs/zh/use-cases/comfyui-for-krita.md b/docs/zh/use-cases/comfyui-for-krita.md new file mode 100644 index 000000000..fd76ea7ec --- /dev/null +++ b/docs/zh/use-cases/comfyui-for-krita.md @@ -0,0 +1,162 @@ +--- +description: 将 ComfyUI 与 Krita 结合使用的教程，学习如何配置 AI 绘画环境，实现本地化的智能创作工作流程。 +--- +# Krita + ComfyUI 实时绘画 +在 Olares 上本地运行 ComfyUI 可以让你灵活地使用端侧 AI 能力，但要让它与你的创作工具无缝配合，还需要一些额外的设置。Olares 支持将 ComfyUI 的功能扩展到其他机器，从而实现与 Krita 等编辑工具的流畅集成。 + +本教程将指导你如何将 Olares 上本地部署的 ComfyUI 实例连接到另一台电脑上运行的 Krita。通过组合 ComfyUI 和 Krita 的优势，你可以打造一个由 AI 驱动的流畅工作流程，让它自然地融入你的创作过程中。 + +## 目标 +通过本教程，你将学习： +- 在 Olares 上部署和配置 ComfyUI，以优化性能和资源利用。 +- 将 ComfyUI 与 Krita 集成，实现无缝的 AI 实时绘画。 + +## 了解组件构成 +你的 AI 艺术工作室由以下三个协同工作的核心部分组成： + +* **ComfyUI**：运行在 Olares 环境中的 AI 引擎，为图像生成提供动力。 +* **Krita**：用于创作和编辑作品的专业级数字艺术软件。 +* **Krita AI Diffusion 插件**：实现 Krita 和 ComfyUI 之间无缝通信的连接器。 + +## 准备工作 +开始之前，请确保具备： +* 已安装且可访问互联网的 Olares 环境 +* 与 Olares 连接到同一本地网络的计算机 +* 足够的系统资源（建议：16GB 内存以获得最佳性能） + +## 配置 ComfyUI + +1. 从应用市场安装 ComfyUI 共享版。 + - 管理员会同时安装 ComfyUI 启动器（管理界面）和 ComfyUI （客户端界面）。 + - 成员仅会安装 ComfyUI。 + + ![安装 ComfyUI](/images/manual/use-cases/install-comfyui.png){width=40%} + +2. 管理员通过 ComfyUI 启动器配置并启动 ComfyUI 后端服务。 + +3. 配置 ComfyUI 的认证级别。 + + a. 打开设置，导航至**应用** > **ComfyUI Shared** > **入口**。 + + b. 将 ComfyUI 的**认证级别**设置为**内部**。 + + ![ComfyUI 认证应用](/images/zh/manual/use-cases/comfyui-authentication-level.png#bordered){width=80%} + :::info + 将 ComfyUI 应用的认证级别设置为“**内部**”后，当你的电脑和 Olares 主机在同一局域网或者通过专用网络访问 Olares 时，你可以在不登录 Olares 的情况下使用 ComfyUI。 + ::: +4. 从桌面启动 ComfyUI，通过生成测试图像验证安装是否成功。 +5. 复制 ComfyUI 地址，以备后续使用。 + :::tip + 出于安全考虑，应始终在 [LarePass 专用网络](../manual/larepass/private-network.md)激活时运行 AI 应用。 + ::: + +## 配置 Krita + +1. 下载 [Krita](https://krita.org/en/download/)。 +2. 下载 [Krita AI Diffusion 插件](https://github.com/Acly/krita-ai-diffusion/releases)。 +3. 启动 Krita，选择**工具** > **脚本** > **从文件导入 Python 插件**，选择下载的 ZIP 压缩文件。 + + ![导入 AI 插件](/images/zh/manual/use-cases/krita-import-plugin.png#bordered){width=70%} +4. 确认插件激活并重启 Krita。 +5. 打开 Krita，在**配置 Krita** > **Python 插件管理**中验证插件安装成功。 + + ![验证 AI 插件](/images/zh/manual/use-cases/krita-verify-plugin.png#bordered) + +## 连接 Krita 和 ComfyUI + +1. 在 Krita 中新建文档。 + :::tip + 建议以 512 x 512 像素的画布开始，以优化性能并高效管理显存。 + ::: +2. 点击**设置** > **面板列表** > **AI Image Generation** 启用插件，你可以将面板放置在便于操作的位置。 + + ![启用 AI 插件](/images/zh/manual/use-cases/krita-enable-plugin.png#bordered) +3. 点击 **Configure**，打开配置对话框。 + + ![配置 AI 插件](/images/manual/use-cases/krita-configure-plugin.png#bordered){width=70%} +4. 设置 ComfyUI 连接。 + + a. 在 **Connection** 中选择 **Custom Server**，粘贴 ComfyUI 的地址。 + + b. 点击 **Connect** 测试连接。出现绿色的“Connected”表示连接成功。 + + ![连接 ComfyUI](/images/manual/use-cases/krita-comfyui-connected.png#bordered) + :::info + 如果连接失败： + - 检查计算机与 Olares 主机是否处于同一网段。如果不在同一网络下，是否已成功开启专用网络功能（网络状态显示为“P2P”或“DERP”）。 + - 检查 ComfyUI 的认证级别是否设为“内部”。 + - 检查 LarePass 专用网络是否开启。 + - 检查计算机是否开启了网络代理服务。如果开启，手动关闭后再重试。 + - 检查 ComfyUI 在 Olares 主机上是否能正常生成图片。 + ::: +5. 调整 ComfyUI 设置。 + + a. 在 **Styles** 中配置偏好的风格模板并选择合适的 **Model checkpoint**。 + + b. 如要使用实时AI绘画功能，建议将 **Performance Preset** 设置为 **Realtime - LCM**，加快出图速度。 + + c. 如果没有其他需求，其他设置项建议使用默认值。 + +## 开始绘画🎨 +现在到了激动人心的部分了！使用自然语言提示开始创作吧！ +### 文生图 +1. 在文本框右下角选择中文，输入提示词，例如“蓝天白云，绿草地上，飞翔着许多粉色水母”。 +2. 点击 **Generate**，浏览生成的图像。 +3. 选择相对满意的图像，点击 **Apply** 将其保存到画布上。 + + ![生成 AI 作品](/images/zh/manual/use-cases/krita-generate-ai-art.png#bordered) + :::tip + 如果生成的图片不够理想，可以尝试： + - 重新生成一批图像 + - 拖动 Strength 的数值调整 AI 的创造性 + - 优化提示词 + - 尝试不同的风格设置 + ::: +### 局部修改 +1. 使用选择工具选取要局部修改的地方。 +2. 在提示词中增加相关的描述，例如“远处有一个小村庄”，点击 **Refine**。 +3. 选择看起来最满意的修改，点击 **Apply**，将局部修改保存到一个新图层。 + + ![局部修改](/images/zh/manual/use-cases/krita-inpaint.png#bordered) +### 实时绘画结合手工调整 +1. 将当前的图像合并为一个图层。 +2. 点击插件左上角模式菜单，选择 **Live** 实时绘图模式。 + + ![启用 Live 实时绘图](/images/zh/manual/use-cases/krita-live-mode.png#bordered) +3. 点击“开始”图标，启动实时绘制。 + + ![实时绘图](/images/zh/manual/use-cases/krita-live-creation.png#bordered) + :::tip + 开始实时绘制后，原图片会被重绘一次，部分细节可能会发生变化，你可以修改 Strength 来控制改变的“力度”。 + 开启实时绘制后，建议先点击右侧的两个对勾按钮保存，并在新图层上进行绘画。 + ::: +4. 在提示词中，描述你想要修改的内容，并在图上绘制对应相应内容。 + 例如，增加“冒着炊烟”的描述，并用白色线条在房顶简单勾勒下炊烟效果。可以看到预览界面已经实时加入了炊烟效果。 + + ![实时绘图](/images/zh/manual/use-cases/krita-add-smoke.png#bordered) + +**最终效果** + + ![实时绘图最终效果](/images/zh/manual/use-cases/krita-live-art-example.png) +### 图生图 +1. 绘制或导入一张人物特定姿势的线稿。 + + ![人物线稿](/images/zh/manual/use-cases/krita-sketch.png#bordered) +2. 输入提示词，例如“一个女生，看着镜头，坐在紫色的床边”。 +3. 点击下方 **Add Control Layer**，选择线稿所在图层，控制方式选择 **Scribble** 涂鸦。 + + ![人物线稿涂鸦绘制](/images/zh/manual/use-cases/krita-sketch-scribble.png#bordered) +4. 点击 **Generate**，从备选图片中选择满意的图片进一步修改。 +5. 开启实时绘画精修手部和其他局部细节。 + + a. 用选择工具选取手部区域，复制到一个新图层。 + + b. 在提示词中输入描述，例如“左手”。 + + c. 开启实时绘画，擦除手部细节。可以直接用文生图生成新的手，也可以简单绘制手的姿势来提高生成的正确率。 + + ![调整局部细节](/images/zh/manual/use-cases/krita-sketch-inpaint.png#bordered) + +**最终效果** + + ![图生图最终效果](/images/zh/manual/use-cases/krita-img-to-img-example.png) \ No newline at end of file diff --git a/docs/zh/use-cases/comfyui-launcher.md b/docs/zh/use-cases/comfyui-launcher.md new file mode 100644 index 000000000..8a23cc940 --- /dev/null +++ b/docs/zh/use-cases/comfyui-launcher.md @@ -0,0 +1,189 @@ +--- +description: 使用 ComfyUI 启动器轻松启动和管理 ComfyUI，包括模型管理、插件配置、环境设置与网络检查等。 +--- +# 使用 ComfyUI 启动器管理 ComfyUI + +ComfyUI 启动器（ComfyUI Launcher）是 ComfyUI 共享版为**管理员用户**提供的核心管理工具。你可以通过启动器来控制 ComfyUI 后台服务的运行状态，并轻松管理模型、插件、运行环境和网络配置。 + +本章节将指导你如何使用 ComfyUI 启动器进行服务的管理和日常维护。 + +## 启动和停止 ComfyUI 服务 + +只有管理员在启动器启动 ComfyUI 服务后，所有集群用户才可以通过客户端界面访问服务。 + +![启动停止服务](/images/zh/manual/use-cases/comfyui-start.png#bordered) + +- **启动 ComfyUI 服务**：点击启动器右上角的**启动**按钮启动 ComfyUI 后台程序。 + + ::: tip 首次运行 + - 首次启动需要进行环境初始化，通常需要等待 10-20 秒。 + - 如果系统提示缺少必要的基础模型，你可以点击**仍然启动**继续启动服务。但请注意，如果缺少基本模型，工作流可能无法正常运行。建议首次安装后先下载必要的基础模型包。 + ::: + +- **停止 ComfyUI 服务**：如果暂时不使用 ComfyUI，可点击启动器右上角的**停止**按钮暂停服务。这会释放 ComfyUI 占用的显存和内存资源。 + +## 管理模型 + +:::tip 注意 +在安装模型之前，请确保你的主机能够正常访问 Github 和 HuggingFace，详细请参考[设置网络](#设置网络环境)。 +::: + +ComfyUI 启动器提供灵活、丰富的模型安装方式。你可以一键安装运行所需基础模型，也可根据需求从 Hugging Face 手动安装或从外部复制。 + +### 一键安装基础模型 + +基础模型即 ComfyUI 运行必要的基础模型，包括 SD 大模型、VAE、预览解码器和辅助工具模型。首次运行时建议先安装基础模型包。 + +1. 通过以下任一方式进入基础模型包安装页面。 + - 在首次启动服务时弹出的**缺少基础模型**提示窗口里，点击**安装模型**。 + - 在启动器首页的**资源包安装**区域，找到**基础模型包**，并点击**查看**。 + +2. 在基础模型安装页面，点击**获取所有资源**开始自动安装。可以通过下方进度条查看安装进度。 + ![安装基础资源包](/images/zh/manual/use-cases/comfyui-install-model.png#bordered) + +### 手动下载模型 +除了基础模型之外，启动器也支持从 HuggingFace 模型库下载，让你轻松获取所需模型： + + + + + + +:::tip 上传外部模型 +如在内置模型库无法找到所需模型，你也可以将外部下载的文件通过文件管理器上传至以下模型目录： + + `外部设备/ai/model`。 +::: + +### 删除模型 +要删除指定模型： + +1. 从启动器左侧导航栏进入**模型管理** > **模型库**。 +2. 在**已安装模型**列表下，找到待删除模型，并点击右侧 delete 按钮以删除。 + +## 管理插件 + +你可以通过 ComfyUI 内置的 ComfyUI-Manager 管理插件，也可以使用启动器的**插件管理**功能。 + +![管理插件](/images/zh/manual/use-cases/comfyui-manage-plugin.png#bordered) + +### 管理可用插件 + +要管理在 ComfyUI Manager 中已注册的可用插件： + +1. 进入**插件管理** > **插件库**。 +2. 在**可用插件**下，选择目标插件： + - 点击 pause 按钮禁用当前运行的插件，点击 play_circle 按钮恢复运行。 + - 点击 delete 按钮删除插件。 + - 点击 download 按钮下载插件。 + - 点击 visibility 按钮查看插件详情。 + - 点击**更新全部插件**按钮更新所有已安装插件。 + - 点击**刷新**按钮刷新插件安装状态。 + +### 从 GitHub 下载插件 + +要从 GitHub 仓库下载插件： + +1. 进入**插件管理** > **自定义安装**。 +2. 输入插件仓库的 URL。 +3. 选择目标分支，默认为 master 或 main 分支。 +4. 点击**安装插件**。 + +## 管理 Python 环境 + +ComfyUI 的运行依赖复杂的 Python 环境。你可以在 **Python 依赖管理**页中管理 ComfyUI 容器中的 Python 依赖库。 + +![管理 Python 环境](/images/zh/manual/use-cases/comfyui-manage-python.png#bordered) + +### 安装新依赖库 + +要安装新依赖库： + +1. 进入 **Python 依赖管理**。 +2. 点击**安装新库**按钮。 +3. 输入库的名称和版本号（可选），点击**安装**。 + +### 管理已安装依赖库 +1. 在 **Python 依赖库** > **已安装 Python 库**下，找到需要操作的 Python 库。 +2. 点击右侧 arrow_upward 按钮以升级库， delete 按钮以删除库。 + +### 分析依赖库安装 +1. 在**依赖分析**页签下，点击**立即分析**按钮。 +2. 在左侧插件列表栏，找到并点击红色高亮的问题插件。 +3. 在**依赖库列表**里，找到缺失的库，并点击右侧**安装**按钮。你也可以点击**一键修复**自动安装所有缺失库。 + + ![分析依赖](/images/zh/manual/use-cases/comfyui-analyze-dependency.png#bordered) + +## 故障排除和维护 + +启动器还提供了一些用于诊断和维护 ComfyUI 服务。 + +### 设置网络环境 + +网络连接问题可能影响模型和插件的下载。使用 ComfyUI 前可在启动器主页查看对 Github、PyPI 和 HuggingFace 的连接状态。 + +![检查网络状态](/images/zh/manual/use-cases/comfyui-view-network.png#bordered) + +例如, GitHub 无法正常访问： + +1. 进入**网络配置**页面。 +2. 切换提供的 GitHub 可访问地址。 +3. 点击**检测**按钮以刷新连接状态。 + +重复第 2、3 步直到网站连接变为"可访问"。 + +![切换网络](/images/zh/manual/use-cases/comfyui-change-network.png#bordered) + +### 查看运行日志 + +你可以导出日志来诊断 ComfyUI 当前的运行状态： + +![查看日志](/images/zh/manual/use-cases/comfyui-log.png#bordered) + + +1. 在启动器首页右上角点击more_vert，再点击**查看日志**以查看当前运行日志。 +2. 点击日志下方refresh以刷新日志，download以下载日志。 + +### 还原 ComfyUI 配置 + +如果你希望将 ComfyUI 还原到初始状态： + +![重置 ComfyUI](/images/zh/manual/use-cases/comfyui-reset.png#bordered) + +1. 在启动器首页右上角点击more_vert，选择**抹掉并还原**。二次确认后，将启动器将开始抹掉和还原程序。 + + +2. 还原操作完成后，重启 ComfyUI 以生效。 + +:::warning 谨慎操作 +还原 ComfyUI 是不可逆的操作，请谨慎选择。 +::: + +## 灵感发现 + +你可以从左侧导航栏进入**灵感发现**页面，查看 [civit.ai](civit.ai) 上最新、最热门的 ComfyUI 模型和工作流。 + +::: tip 注意 +请确认你的网络可以正常访问 [civit.ai](civit.ai)。 +::: + + + diff --git a/docs/zh/use-cases/comfyui.md b/docs/zh/use-cases/comfyui.md new file mode 100644 index 000000000..9290e3ef9 --- /dev/null +++ b/docs/zh/use-cases/comfyui.md @@ -0,0 +1,48 @@ +--- +description: ComfyUI 在 Olares 上的使用指南，通过节点式界面精确控制 AI 图像生成过程，创建可重用的工作流程。 +--- +# ComfyUI + +ComfyUI 是一款基于节点的 Stable Diffusion 图形界面工具。它把 AI 绘图过程变成了可视化编程，让使用者能像搭建积木一样，通过连接各种功能节点来实现完整的绘图流程。从提示词编写、模型选择到后期处理，每个环节都能精确把控。 + +与 Stable Diffusion WebUI 简单直观的界面不同，ComfyUI 让你通过组合代表不同功能的节点，可以构建出自己的工作流程。这不仅让你能更好地掌控绘图过程，还可以把常用的复杂操作保存下来重复使用，也方便与他人分享。 + +## ComfyUI 能做什么？ +通过 ComfyUI，你可以实现以下功能： + +* 用可视化方式搭建和复用工作流 +* 对绘图流程进行精细调优 +* 自由组合不同模型和技术 +* 导出导入工作流，方便分享 +* 使用相同配置批量处理图片 +* 添加高级图像后期效果 + +## 安装 ComfyUI 共享版 +Olares 应用商店提供 ComfyUI 共享版，可允许同一 Olares 集群上的多个用户共享 ComfyUI 的模型、插件和工作流资源。它还提供了一个启动器（ComfyUI Launcher），帮助管理员用户管理 ComfyUI 资源和运行环境。 + +::: tip 注意 +自 1.11.6 版本起，Olares 会使用 ComfyUI 共享版取代之前的集群范围应用。如果安装过 ComfyUI For Cluster 和对应的 ComfyUI 客户端，请卸载后再安装共享版。 +::: + +要安装 ComfyUI 共享版： + +1. 打开 Olares 应用市场，找到 ComfyUI 共享版，并点击**获取**。 + + - 管理员将会在 Olares 桌面看到两个图标：一个是 ComfyUI 客户端界面，另一个是 ComfyUI 启动器。 + + ![安装 ComfyUI 共享版](/images/manual/use-cases/install-comfyui.png){width=40%} + + - 成员用户只会在桌面看到 ComfyUI 客户端界面。 + + :::tip 启动 ComfyUI 服务 + 管理员必须从启动器启动 ComfyUI 服务之后，集群中的所有用户才能从客户端入口访问服务。 + ::: + +2. 点击 ComfyUI 图标打开界面。管理员也可以从启动器进入 ComfyUI 界面。 + + ![ComfyUI](/images/manual/use-cases/comfyui.png#bordered) + +## 了解更多 + +- [使用 ComfyUI 启动器管理 ComfyUI](comfyui-launcher.md) +- [Krita + ComfyUI 实时绘画](comfyui-for-krita.md)：了解如何利用 ComfyUI 助力 Krita 中的创意工作流。 \ No newline at end of file diff --git a/docs/zh/use-cases/dify.md b/docs/zh/use-cases/dify.md new file mode 100644 index 000000000..f4855941f --- /dev/null +++ b/docs/zh/use-cases/dify.md @@ -0,0 +1,69 @@ +--- +description: Dify 在 Olares 上的部署教程，帮助你快速构建和管理 AI 应用，打造专属的智能服务生态系统。 +--- +# Dify 定制 AI 助手 +Dify 是一个 AI 应用开发平台。它是 Olares 集成的关键开源项目之一，帮助你构建和管理 AI 应用，同时确保数据完全由自己掌控。 +此外，你也可以在 Dify 中接入个人知识库文档，让 AI 应用更懂你。 + +## 开始之前 +要使用本地 AI 模型，请确保你的环境中已配置以下内容： +- Olares 环境中已安装并运行 [Ollama](ollama.md)。 +- 已安装 [Open WebUI](openwebui.md)，并下载了你偏好的语言模型。 +- 访问设备已安装 LarePass 并已[启用专用网络](../manual/larepass/private-network.md)。 + :::tip 提示 + 建议使用 `gemma2` 或 `qwen` 等轻量但功能强大的模型，可在速度和性能间取得良好平衡。 + ::: + +## 安装 Dify +:::info +从 Olares 1.11.6 开始，如果已安装 "Dify For Cluster" 或 "Dify"，需先卸载这些版本。 +::: + +1. 从应用市场中安装 “Dify 共享版”。 +2. 从桌面打开 Dify。请确保管理员已安装 Dify 共享版。 + +## 创建 AI 助手应用 + +1. 打开 Dify，在**工作室**选项卡下，点击**创建空白应用**创建一个 AI 助手应用。这里我们创建一个名为 “Ashia” 的 Agent。 + ![创建应用](/images/zh/manual/use-cases/dify-create-app.png#bordered) + +2. 右侧点击**去设置**，进入模型供应商配置页面。你可以选择远程模型或本地托管模型。 + ![应用初始页面](/images/zh/manual/use-cases/dify-app-init.png#bordered) + +## 添加 Ollama 作为模型提供商 + +1. 进入**设置** > **应用** > **Ollama** > **入口**，设置 Ollama 的认证级别为“内部”。该设置允许其他应用在本地网络环境下可无需认证即可访问 Ollama 服务。 + + ![Ollama entrance](/images/zh/manual/use-cases/dify-ollama-entrance.png#bordered) + +2. 在 Dify 的 模型提供者商配置页面，选择 Ollama 作为模型提供者商，并进行以下配置： + - **模型名称**：填写模型名称，例如：`gemma2`。 + - **基础 URL**：填入 Ollama 本地地址: `https://39975b9a1.{username}.olares.cn`。将 `{username}` 替换为 Olares 管理员的用户名。例如：`https://39975b9a1.marvin123.olares.com`。 + + ![配置 Ollama](/images/zh/manual/use-cases/dify-add-gemma2.png#bordered){width=70%} + + :::info 提示 + 其他必填字段可以保留默认值。 + ::: +3. 点击**保存**。 + +## 配置 Ashia + +1. 切换至 Dify 的**工作室**选项，并进入 **Ashia** 应用。 +2. 从右侧模型列表中选择已配置好的 Gemma2 本地模型。 + + ![选择模型](/images/zh/manual/use-cases/dify-select-model.png#bordered) +3. 点击**发布**。现在可以在**调试与预览**窗口试着和 Gemma2 聊天了。 + + ![聊天](/images/zh/manual/use-cases/dify-chat-with-ashia.png#bordered) + +## 设置本地知识库 +1. 在 Dify 中，进入**知识库**选项卡。 +2. 找到你的默认知识库。Dify 会监听你 Olares ID 名下的 `/Documents` 文件夹，作为其默认知识库。 + ![默认知识库](/images/zh/manual/use-cases/dify-default-knowledge-base.png#bordered) +3. 进入 `/Documents` 文件夹，添加文档至知识库。 + ![添加文档](/images/zh/manual/use-cases/dify-add-kb-file.png#bordered) +4. 在 Ashia 的编排页面中，点击 **add添加**，选择创建的知识库，为 Ashia 添加上下文支持。 + ![添加知识库](/images/zh/manual/use-cases/dify-add-knowledge-base.png#bordered) +5. 点击**发布**。现在有了知识库的帮助，你可以试着向助手问一个专业问题： + ![知识库聊天](/images/zh/manual/use-cases/dify-chat-kb.png#bordered) \ No newline at end of file diff --git a/docs/zh/use-cases/host-cloud-android.md b/docs/zh/use-cases/host-cloud-android.md new file mode 100644 index 000000000..db0bcee27 --- /dev/null +++ b/docs/zh/use-cases/host-cloud-android.md @@ -0,0 +1,266 @@ +--- +outline: [2, 3] +description: 在 Olares 上部署云端 Android 模拟器 redorid，并在 Mac 和 Windows 上通过 adb 和 scacpy 访问云端 Android 主机。 +--- + +# 使用 redroid 搭建云端 Android + +[redroid](https://github.com/remote-android/redroid-doc) (Remote Android) 是一款支持 GPU 加速的云端 Android（Android in Cloud）解决方案，完美适配 Olares。redroid 让你轻松在 Olares 上托管高性能 Android 实例，随时随地访问并运行 Android 游戏、应用，甚至进行批量自动化测试。 + +本教程将带你在 Olares 上完成 redroid 的安装与配置，并从 Windows 和 macOS 上远程连接、操控 Android 实例。 + +## 目标 +通过本教程，你将学习： +- 在 Olares 宿主机上安装并配置 redroid 所需的内核依赖。 +- 在 Olares 上安装 redroid 应用并获取对外服务 URL。 +- 通过 Windows 和 macOS 上通过 `adb` 和 `scrcpy` 连接并操控 Android 实例。 +- 在 Android 实例上安装 APK 应用。 + +## 开始之前 +在开始之前，请确保满足以下条件： +- Olares 已安装并运行。 + + ::: tip 配置要求 + - redroid 仅支持在 Linux 上运行，请确保你的 Olares 实例部署在 Linux 系统上。 + - redroid 运行时会消耗较高系统资源。为获得更佳性能，建议使用至少 8 核 CPU 和 16GB 内存的主机运行 Olares。 + ::: + +- 在连接设备上安装 LarePass 客户端并启用[专用网络](../manual/larepass/private-network.md)。可在 [LarePass 官网](https://olares.cn/larepass)下载正确的版本。 + + ## 安装内核依赖模块 + + 在 Linux 系统运行安卓模拟服务需要安装特定内核依赖模块，详见 [redroid 项目文档](https://github.com/remote-android/redroid-doc/blob/master/deploy/README.md)。 + +以 Ubuntu 系统为例，可在终端执行以下命令安装所需内核模块： + +```bash +sudo apt install linux-modules-extra-`uname -r` +sudo modprobe binder_linux devices="binder,hwbinder,vndbinder" +# 以下命令可能会报错，高内核版本可忽略 +sudo modprobe ashmem_linux +``` + +## 在 Olares 上安装 redroid + +redroid 在 Olares 上以无界面的服务后端运行。要安装 redroid： + +1. 打开 Olares 应用市场，在“系统工具”分类下找到 redroid，点击**获取**。安装成功后，redroid 会自动运行。 +2. 获取 redroid 对外服务的地址： + + a. 从 Olares 桌面进入**设置** > **应用** > **redroid**： + + b. 在**端点设置**里获取 redroid 应用的基础域名: `beb583c3..olares.cn`。 + + c. 将 redroid 对外服务端口 `46878` 附在基础域名后。 + + 这样，我们就得到了 redroid 的对外服务网址，如 `beb583c3.olares01.olares.cn:46878`。 + +## 连接 redroid 服务 + +要访问 Olares 托管的 Android 实例，我们需要用安卓调试程序 `adb` 连接 redroid 服务，然后用 `scrcpy` 进行视频和音频渲染。 + + + + + + + +## 安装 APK 应用 + +连接成功后，你可以尝试用 `adb` 为远程 Android 实例安装一个三方应用。 + + + + + + +安装成功后，重新执行 `scrcpy` 命令连接 Android。上划屏幕，就能看到刚刚安装的应用了。 + + +## 常见 `adb` 命令参考 +:::tip 注意 +以下提供命令适用于 macOS 及 Linux 系统。Windows 系统用户请在 `adb` 命令后加上 `.exe`。 +::: + +```bash +# 启动adb +adb start-server +# 连接设备 +adb connect url:port +# 查看当前已连接设备列表 +adb devices +# 断开链接 +adb disconnect url:port +# 手动安装应用 +adb -t 3(transport_id，设备列表可看到) install xx.apk +# 查看日志 +adb logcat +# 导出日志 +adb logcat -v time > log.txt +# 将文件从本地推送到设备 +adb push <本地路径> <设备路径> +# 将文件从设备拉取到本地 +adb pull <设备路径> <本地路径> +# 列出设备目录内容 +adb shell ls <路径> +# 查看设备文件内容 +adb shell cat <文件路径> +# 重启 +adb shell +# 关机 +adb shell reboot -p +``` + + + + + + diff --git a/docs/zh/use-cases/index.md b/docs/zh/use-cases/index.md new file mode 100644 index 000000000..8024ba781 --- /dev/null +++ b/docs/zh/use-cases/index.md @@ -0,0 +1,19 @@ +--- +description: 了解 Olares 在 AI 流程、创意工具和自托管应用中的实际用例，充分释放 Olares 的潜力。 +--- + +# 使用场景与教程 + +本节聚焦于**真实场景**，帮助你充分挖掘 Olares 的强大功能。 从运行 AI 模型到在自托管服务间构建无缝工作流，这些动手教程将指导你完成具体任务，并利用已安装的应用实现完整、实用的解决方案。 + + diff --git a/docs/zh/use-cases/ollama.md b/docs/zh/use-cases/ollama.md new file mode 100644 index 000000000..17ed39060 --- /dev/null +++ b/docs/zh/use-cases/ollama.md @@ -0,0 +1,83 @@ +--- +outline: [2, 3] +description: 了解如何在 Olares 环境中使用 Ollama CLI 在本地下载和管理 AI 模型。 +--- + +# 通过 Ollama 在本地运行 AI 模型 +Ollama 是一个轻量级平台，可以让你在本地机器上直接运行 `deepseek-r1` 和 `gemma3` 等开源 AI 模型。如果你更偏向于使用图形化界面，也可以在 Open WebUI 中管理 Ollama 模型，以添加更多功能并简化交互。 + +本文档将介绍如何在 Olares 上设置和使用 Ollama CLI。 + +## 开始之前 +请确保满足以下条件： +- 当前登录账号为 Olares 管理员。 +- 确保设备已安装 LarePass 并[启用专用网络](../manual/larepass/private-network.md#在-larepass-中启用专用网络)。 + +## 安装 Ollama + +直接从应用市场安装 Ollama。 + +安装完成后，可以从启动台访问 Ollama 终端。 + +![Ollama](/images/manual/use-cases/ollama.png#bordered) +## Ollama CLI +Ollama CLI 让你可以直接管理和使用 AI 模型。以下是主要命令及其用法： + +### 下载模型 +:::tip 查看 Ollama 模型库 +如果不确定下载哪个模型，可以在 [Ollama Library](https://ollama.com/library) 浏览可用模型。 +::: +使用以下命令下载模型： +```bash +ollama pull [model] +``` + +### 运行模型 +:::tip +如果尚未下载指定的模型，ollama run 命令会在运行前自动下载该模型。 +::: + +使用以下命令运行模型： +```bash +ollama run [model] +``` + +运行命令后，直接在 CLI 中输入问题，模型会生成回答。 + +完成交互后，输入： +```bash +/bye +``` +这将退出会话并返回标准终端界面。 + +### 停止模型 +要停止当前运行的模型，使用以下命令： +```bash +ollama stop [model] +``` + +### 列出模型 +要查看系统中已安装的所有模型，使用： +```bash +ollama list +``` + +### 删除模型 +如果需要删除模型，可以使用以下命令： +```bash +ollama rm [model] +``` +### 显示模型信息 +要显示模型的详细信息，使用： +```bash +ollama show [model] +``` + +### 列出运行中的模型 +要查看所有当前运行的模型，使用： +```bash +ollama ps +``` + +## 了解更多 +- [了解如何通过 Open WebUI 运行 Ollama 模型](openwebui.md) \ No newline at end of file diff --git a/docs/zh/use-cases/openwebui.md b/docs/zh/use-cases/openwebui.md new file mode 100644 index 000000000..7876482aa --- /dev/null +++ b/docs/zh/use-cases/openwebui.md @@ -0,0 +1,107 @@ +--- +outline: [2, 3] +description: Open WebUI 使用教程，包括模型管理、语音交互和图像生成功能配置，轻松搭建私有 AI 助手服务。 +--- + +# Open WebUI + +Open WebUI 为大语言模型（LLM）提供了直观的管理界面，支持 Ollama 和 OpenAI 兼容的 API。本指南将帮助你在 Olares 中设置和配置 Open WebUI，包括： + +* 模型管理 +* 语音交互（语音转文字和文字转语音） +* 图像生成功能 + +:::tip 打开 LarePass 专用网络 +确保访问设备已安装 LarePass 并 [启用专用网络](../manual/larepass/private-network.md#在-larepass-中启用专用网络)以确保安全、流畅的访问体验。 +::: + +## 安装 Ollama 和 Open WebUI +使用 Open WebUI 前需要先安装 Ollama： +* **管理员**：需要同时安装“Ollama”和“Open WebUI”。 +* **团队成员**：仅需安装“Open WebUI”，同时确保管理员已安装“Ollama”。 + +![安装 Ollama 和 Open WebUI](/images/manual/use-cases/install-open-webui.png){width=30%} + +:::info Open WebUI 账号 +首次使用时需要创建本地 Open WebUI 账号。这个账号仅限用于你的 Olares 环境，不会与任何外部服务连接。 +请注意，其他环境中创建的 Open WebUI 账号在这里无法使用，你需要重新创建一个新账号。 +::: + +## 下载模型 +:::tip 如何选择模型？ +下载前可以在 [Hugging Face Chatbot Arena Leaderboard](https://huggingface.co/spaces/lmsys/chatbot-arena-leaderboard) 浏览可用模型，并在 [Ollama 模型库](https://ollama.com/library)中确认模型名称。 +::: + +推荐以下入门级模型（参数量在 13B 及以下）以获得最佳性能： + +* `gemma2`：Google 最新推出的高效强大语言模型 +* `llama3.2`：Meta 最新的开源视觉语言模型 + +### 快速下载 +1. 在首页点击下拉菜单，输入模型名称（如 `llama3.2`）。 +2. 选择 从 Ollama.com 拉取，下载会自动开始。 + + ![从首页下载模型](/images/zh/manual/use-cases/openwebui-download-model-quick.png#bordered) +### 通过设置下载 +1. 点击左下角的用户名称，选择**管理员面板** > **设置** > **模型**。 +2. 在**从 Ollama.com 拉取模型**字段下输入模型名称（如 `llama3.2`）。 +3. 点击 download 开始下载。 + + ![从设置下载模型](/images/zh/manual/use-cases/openwebui-download-model-settings.png#bordered) + +## 配置语音功能 +### 语音转文字 +1. 根据角色安装 Faster Whisper： + - **管理员**：需要同时安装“Faster Whisper For Cluster”和“Faster Whisper”。 + - **团队成员**：仅需安装“Faster Whisper”，同时确保管理员已安装“Faster Whisper For Cluster”。 + + ![Install Faster Whisper](/images/manual/use-cases/install-faster-whisper.png){width=40%} + +2. 打开 Open WebUI，进入**管理员面板** > **设置** > **音频**。 +3. 选择 OpenAI 作为语音转文字引擎，配置如下： + - **API 基础 URL**：`http://whisper.whisper-{管理员本地名称}:8000/v1`，例如：`http://whisper.whisper-alice123:8000/v1`。 + - **API 密钥**：输入任意字符 +4. 输入模型版本，默认为 `whisper-1`。你可以选择： + - `tiny.en` + - `tiny` + - `base.en` + - `base` + - `small.en` + - `small` + - `medium.en` + - `medium` + - `large-v1` + - `large-v2` + - `large-v3` + - `large` + - `distil-large-v2` + - `distil-medium.en` + - `distil-small.en` + - `distil-large-v3` +5. 点击**保存**。 +6. 配置完成后启动 Faster Whisper。你会看到在 Open WebUI 中配置的模型已自动加载。此时你可以： + - 直接上传音频开始转录 + - 调整参数，包括： + - 选择不同的子模型 + - 选择任务类型 + - 配置"温度"设置 + + ![配置 Faster Whisper](/images/zh/manual/use-cases/openwebui-faster-whisper.png#bordered) + +### 文字转语音 +1. 管理员安装 OpenedAI Speech 应用，在集群内启动 OpenAI Speech 服务。 +2. 打开 Open WebUI，进入**管理员面板** > **设置** > **音频**。 +3. 选择 OpenAI 作为文字转语音引擎，配置如下： + - **API 基础 URL**：`http://openedaispeech.openedaispeech-{管理员本地名称}:8000/v1`，例如：`http://openedaispeech.openedaispeech-alice123:8000/v1`。 + - **API 密钥**：输入任意字符 +4. 点击**保存**。 + +### 文字转图像 +在 Olares 环境中安装了 SD Web UI 共享版后，你可以直接通过 Open WebUI 使用 Stable Diffusion 的强大图像生成功能。 + +1. 管理员安装 SD Web UI 共享版，在集群里启动 Stable Diffusion 服务。 +2. 打开 Open WebUI，进入**管理员面板** > **设置** > **图像**。 +3. 选择 **Automatic1111** 作为图像生成引擎，基础 URL 为：`http://sdwebui.sdwebui--{管理员本地名称}:7860`，例如：`http://sdwebui.sdwebui-alice123:7860`。 +4. 点击 cached 验证连接。 +5. 开启**图像生成（实验性）**，选择你偏好的文本生成图像模型检查点。 +6. 点击**保存**。 \ No newline at end of file diff --git a/docs/zh/use-cases/perplexica.md b/docs/zh/use-cases/perplexica.md new file mode 100644 index 000000000..0163e4814 --- /dev/null +++ b/docs/zh/use-cases/perplexica.md @@ -0,0 +1,45 @@ +--- +description: Perplexica 应用配置指南，实现高性能 AI 对话服务，支持个性化调整和数据隐私保护。 +--- +# Perplexica 本地 AI 搜索 + +Perplexica 是一个开源的 AI 搜索引擎，在提供智能搜索功能的同时注重保护用户隐私。作为 Perplexity AI 的替代方案，它将先进的机器学习技术与全面的网络搜索功能相结合，为你的查询提供准确且附带来源引用的答案。 + +## 后端引擎：SearXNG +SearXNG 作为 Perplexica 的后端，是一个注重隐私的元搜索引擎。它具有以下特点： +* 聚合多个搜索引擎的结果 +* 去除跟踪代码，保护你的隐私 +* 为 AI 模型提供干净、无偏见的搜索结果 + +通过这样的集成，Perplexica 既能作为完整的搜索解决方案，又能确保敏感信息的安全。 + +## 开始之前 +在开始使用前，请确保： +- Olares 环境中已安装并运行 Ollama +- Open WebUI 已安装，并已下载所需的语言模型 + :::tip + 建议使用 `gemma2` 等轻量但功能强大的模型，可在速度和性能间取得良好平衡。 + ::: +- 确保访问设备已安装 LarePass 并[启用专用网络](../manual/larepass/private-network.md#在-larepass-中启用专用网络)。 + +## 配置 Perplexica +1. 管理员从应用市场安装 SearXNG。 + + :::info + 从 Olares 1.11.6 开始，如果已安装 "SearXNG For Cluster" 或 "SearXNG" 客户端入口，需先卸载这些版本。 + ::: + +2. 安装 Perplexica。 +3. 启动 Perplexica，点击左下角的 settings 打开设置界面。 +4. 配置搜索环境。以 `gemma2` 为例： + - **Chat model provider**：`Ollama` + - **Chat model**：`gemma2:latest` + - **Embedding model provider**：`Ollama` + - **Embedding model**：`gemma2:latest` + + ![Perplexica 配置](/images/manual/use-cases/perplexica-configurations.png#bordered){width=50%} +5. 点击底部的 cloud_upload 确认按钮保存配置并返回搜索界面。 + +至此配置完成。你可以搜索感兴趣的主题来测试新的搜索环境。 + +![Perplexica 示例](/images/manual/use-cases/perplexica-example-question.png#bordered) diff --git a/docs/zh/use-cases/stable-diffusion.md b/docs/zh/use-cases/stable-diffusion.md new file mode 100644 index 000000000..d940e6faa --- /dev/null +++ b/docs/zh/use-cases/stable-diffusion.md @@ -0,0 +1,82 @@ +--- +description: 在 Olares 上部署 Stable Diffusion 的指南，包括模型安装、多用户配置和系统优化，轻松实现 AI 图像生成。 +--- +# Stable Diffusion + +Stable Diffusion 是基于潜在扩散模型（LDM）的新一代 AI 图像生成技术。它通过在低维空间处理图像生成过程，显著降低了计算需求，同时保持了高保真度的输出质量。 + +通过 Olares 平台，你可以轻松部署和管理 Stable Diffusion。无需关注文件系统和数据库等底层配置，直接进入创作环节。 + +借助 Olares 的多用户支持特性，团队成员可以共享同一个 Stable Diffusion 部署实例，并确保各自数据的私密性。这种方式避免了重复安装系统而过度消耗硬件资源的问题。 + +## Stable Diffusion 能做什么？ + +无论你是想扩展创作工具库的艺术家、将 AI 图像集成到工作流程中的开发者，还是对 AI 艺术创作充满好奇的探索者，Stable Diffusion 能支持： + +* 将文字描述转换为图像 +* 基于参考图片生成新图像 +* 对已有图片进行局部重绘或扩展 +* 图像风格迁移和艺术化处理 +* 生成高清图像及超分辨率处理 + +## 安装 SD Web UI +:::info +从 Olares 1.11.6 开始，如果已安装 "SD Web UI For Cluster" 或 "SD Web UI" 客户端入口，需先卸载这些版本。 +::: + +1. 从应用市场里安装 SD Web UI 共享版。 +2. 在桌面启动 SD Web UI 图标开始创作。请确保管理员已安装 SD Web UI 共享版。 + +## 多人使用避免冲突 + +模型检查点（checkpoint）默认采用全局共享机制——当有用户切换检查点后，其他用户的后续操作都会使用新选择的检查点。为避免互相影响，建议在创建任务时指定专用检查点。 + +![检查点配置说明](/images/manual/use-cases/sd-checkpoint.png) + +1. 全局检查点设置 +2. 单任务检查点设置 + +## 修改参数配置 +在 Olares 中，启用 SD Web UI 默认使用 `--xformers` 参数，用于： +- 减少显存占用 +- 加速图像生成 +- 支持更高分辨率图像 + +但是， `--xformers` 会带来一定影响： +- 生成图像的风格多样性可能降低 +- 对提示词的解释准确度略有下降 + +如需移除该参数，请按以下步骤操作： + +:::info +只有 Olares 管理员可以通过控制面板应用调整系统参数。 +::: + +1. 在控制面板中，选择**浏览**。 +2. 在管理员命名空间下找到 **sdwebui**。 +3. 在**部署**中点击 **sdwebui**。 +4. 点击右上角菜单 more_vert，选择**编辑 YAML**。 +5. 在 YAML 编辑器中找到并删除 `--xformers` 参数。默认的 YAML 文件内容类似如下： + + ```yaml {5} + env: + - name: CLI_ARGS + value: >- + --allow-code --enable-insecure-extension-access --api + --no-hashing --gradio-queue --xformers + ``` + +6. 点击**确定**使变更生效。 + +## 画廊 + + + + + + + + + + +
示例图片 1示例图片 2
示例图片 3示例图片 4
\ No newline at end of file diff --git a/docs/zh/use-cases/stream-game.md b/docs/zh/use-cases/stream-game.md new file mode 100644 index 000000000..b8e321ab8 --- /dev/null +++ b/docs/zh/use-cases/stream-game.md @@ -0,0 +1,140 @@ +--- +outline: [2, 3] +description: 在 Olares 上安装 Steam Headless，配置串流服务，并使用 Moonlight 从本地或远程网络串流 Steam 游戏。 +--- + +# 使用 Steam Headless 串流喜爱的游戏 + +想要利用 Olares 的强大性能放松一下？没有问题。借助 Steam Headless 应用，Olares 轻松化身为 Steam 串流服务器，让你可以通过 Moonlight 或 Steam Link 客户端在任意兼容设备上畅玩你最爱的游戏大作。 + +本教程将带你完成 Steam Headless 应用的安装、串流服务的配置、以及通过 Moonlight 客户端进行游戏串流。 + +## 目标 +通过本教程，你将学习： + +- 在 Olares 上安装 Steam Headless，并在 Steam 客户端上打开 Windows 游戏的兼容性。 +- 配置 Sunshine 串流服务并与 Moonlight 客户端上的主机配对。 +- 通过 Moonlight 客户端在本地或远程网络上进行游戏串流。 + +## 准备工作 + +开始前，请确保以下条件已满足： +- Olares 已在配有 NVIDIA 显卡的主机上运行。 +- 串流设备已安装 Moonlight 客户端。可访问 [Moonlight 官网](https://moonlight-stream.org/)下载适合你设备的客户端并安装。 +- 确保串流设备已安装 LarePass 并[启用专用网络](../manual/larepass/private-network.md#在-larepass-中启用专用网络)。 +- 拥有一个有效的 Steam 账号以访问你的游戏。 + +## 安装 Steam Headless + +1. 打开 Olares 应用市场，在“娱乐”分类下找到 Steam Headless 并点击**获取**。 +2. 安装完成后，打开应用，然后点击 **Connect** 进入 Steam Headless 的控制台。 +3. 点击 **Install** 按钮以安装并更新 Steam 客户端。安装完毕后会自动跳转至 Steam 登录页面。 + ![安装 Steam](/images/manual/tutorials/install-steam-client.png#bordered) + +4. 登录你的 Steam 账号并完成基本设置。 + + ![Steam 登录界面](/images/zh/manual/tutorials/steam-login.png#bordered) + +::: tip 重试安装 +由于国内网络环境限制，Steam 客户端安装和更新可能失败，此时可从 Steam Headless 控制台左上角进入 **Applications** > **Internet** > **Steam** 以重新安装。多次尝试一般可以成功。 +::: + +## 设置 Steam 游戏兼容性 + +Olares 运行于 Linux 环境，需要通过 [Proton](https://github.com/ValveSoftware/Proton) 兼容层运行 Steam 上的 Windows 平台游戏。 + +1. 在 Steam 客户端页面左上角，点击 **Steam** > **设置**。 +2. 点击**兼容性**选项，打开**为所有其他产品启用 Steam Play**。 + ![Steam 设置](/images/zh/manual/tutorials/steam-setting.png#bordered) +3. 保存设置后重启 Steam 客户端即可查看全部游戏库。 + +## 配置串流服务 + +Steam Headless 集成了 Sunshine 串流服务器。要使用 Moonlight 客户端串流，还需在 Moonlight 上将游戏主机与 Sunshine 配对。 + +### 准备配对 + +1. 从浏览器获取 Steam Headless 页面的 URL，并添加端口号 `:47990`，如 `https://139ebc4f0.<你的olares ID>.olares.cn:47990`。通过该网址访问 Sunshine 串流服务器的控制页面。 + + ![Sunshine 控制台](/images/manual/tutorials/access-sunshine.png#bordered) + +2. 首次访问时，请使用以下默认凭据登录： + - 用户名：`sam` + - 密码：`password` +3. 点击 **Pin** 标签进入配对页面，你将看到输入配对码的提示。 + + ![Sunshine 配对页面](/images/manual/tutorials/pin-sunshine.png#bordered) + +### 在 Moonlight 端添加主机 + +1. 在串流设备上打开 Moonlight 客户端，点击右上角 add_to_queue 按钮添加主机。 +2. 输入主机 IP 地址，即 Steam 的本地 URL：`139ebc4f0.<你的olares ID>.olares.cn`。 + + ::: tip 注意 + 仅需填入 URL 部分（无需 `https://`）。 + ::: + +3. 点击**确定**，界面上会出现一个锁定状态的主机图标。 +4. 点击主机图标获取配对码。 + + ![获取配对码](/images/manual/tutorials/get-pin-code.png#bordered) + +### 完成配对 + +1. 在 Sunshine 的配对页面中输入配对码和设备名称。 +2. 点击 **Send** 完成配对。配对成功后，你将看到提示信息："Success! Please check Moonlight to continue"。 +3. 返回 Moonlight 界面，主机图标应变为激活状态。 + + ![配对成功](/images/manual/tutorials/active-host-moonlight.png#bordered) + +## 开始串流 + +配置完成后，尽情享受串流游戏的乐趣吧。 + +### 本地串流 + +如果你的串流设备与 Olares 处于同一局域网中： + +1. 在串流设备上打开 Moonlight 客户端。 +2. 点击主机图标，之后点击 Steam 图标进入 Steam Big Picture 模式开始游戏。 + + ![进入串流](/images/manual/tutorials/stream-success.png#bordered) + +### 远程串流 + +借助 Olares 的专用网络，即使不在同一网络中，也能获得流畅的游戏串流体验。 + +启用专用网络的步骤如下： + + + +开启专用网络后，操作步骤与本地串流一致。 + +## 常见问题 + +### 为什么我看到的画面不是全屏？ + +可能是分辨率设置问题。你可以尝试以下方式： + +- 在 Moonlight 中进入**设置** > **基本设置** > **分辨率和帧率**进行调整。 +- 从 Steam Headless 控制台左上角进入 **Applications** > **Settings** > **Display** 中修改分辨率。 + + ![调整显示设置](/images/manual/tutorials/set-steam-display.png#bordered) + +### 如何在全屏模式下退出串流？ + +要退出串流的游戏画面： +- **Windows**：请使用快捷键组合 **Ctrl + Alt + Shift + Q**。 +- **Mac**：请使用快捷键组合 **Control (^) + Option (⌥) + Shift + Q**. +- **移动设备**：请使用手柄按键组合 **Start + Select + L1 + R1**。 + +游戏结束后，建议退出 Steam Big Picture 模式以释放 Olares 系统资源。 + +### 我下载的游戏存在哪里？ + +默认情况下，默认情况下，游戏下载目录为： + + `/Cache/olares/steam-headless/c0/.steam/debian-installation/steamapps/common`。 + +建议不要修改默认下载路径。 + diff --git a/docs/zh/use-cases/stream-media.md b/docs/zh/use-cases/stream-media.md new file mode 100644 index 000000000..30384d12a --- /dev/null +++ b/docs/zh/use-cases/stream-media.md @@ -0,0 +1,81 @@ +--- +outline: [2, 3] +description: 通过 Olares 搭建私人流媒体服务器，配置 VPN 远程访问、管理媒体文件、使用 Jellyfin 进行视频串流播放。 +--- +# 远程观看 Olares 中下载的视频 +无论是在家还是在外，Olares 都能让你轻松访问个人媒体库。借助内置的专有网络功能和 Jellyfin 等应用，你可以随时随地安全流畅地观看自己收藏的影视作品。本教程将为你介绍如何设置 Olares 专有网络、访问媒体文件，以及配置 Jellyfin。 + +## 目标 +通过本教程，你将学习： +- 配置 Olares 专有网络，实现从任何地方安全访问媒体库，获得局域网般的访问体验。 +- 通过 LarePass 客户端或网页浏览器浏览和播放存储在 Olares **文件管理器**中的视频文件。 +- 安装和设置 Jellyfin 以实现串流。 + +## 打开 Olares 专用网络 +为了在不同网络中实现流畅的流媒体播放，需要在 LarePass 中[启用专用网络](../manual/larepass/private-network.md#在-larepass-中启用专用网络)。 +启用专用网络的设备无论是通过 LarePass 客户端还是浏览器访问 Olares，都会使用专用网络连接。 + +:::tip +如需下载不同版本的 LarePass，请访问[官方页面](https://olares.cn/larepass)。 +::: + + + +## 在 LarePass 中访问媒体文件 +启用专用网络后，你可以浏览存储在 Olares 上的媒体文件。 + +### 通过 LarePass 客户端访问 +1. 打开 LarePass，点击**文件**，进入包含电影和电视剧的媒体目录。 +2. 点击任意视频文件，即可在电脑或移动设备上开始播放。 + +![在 LarePass 客户端中播放视频](/images/zh/manual/use-cases/view-video-from-larepass-desktop.png#bordered) + +### 通过浏览器访问 +1. 以网页模式打开**文件管理器**，或者直接使用其 URL：`https://files.[OlaresDomainName]`。 + + ![打开文件管理器](/images/zh/manual/use-cases/view-video-from-files.png#bordered) +2. 找到你的媒体目录，点击视频文件即可开始播放。 + + ![从文件管理器播放视频](/images/zh/manual/use-cases/view-video-from-files-2.png#bordered) + +## 使用 Jellyfin 访问媒体文件 +如果需要高级媒体管理功能，例如字幕支持和多声道音频，可以安装 Jellyfin。 + +1. 打开应用市场，进入**娱乐**分类。 +2. 找到并下载 Jellyfin。 +3. 启动 Jellyfin，并完成首次设置： + - 设置管理员密码。 + + ![设置管理员密码](/images/zh/manual/use-cases/jellyfin-set-admin.png#bordered) + - 配置媒体库目录。 + + ![设置管理员密码](/images/zh/manual/use-cases/jellyfin-set-media-library.png#bordered) +4. 等待 Jellyfin 扫描并索引你的媒体库。它会自动获取以下元数据： + - 电影海报 + - 描述信息 + - 演职员表 + + ![Jellyfin](/images/zh/manual/use-cases/jellyfin-details.png#bordered) + +## 通过 Jellyfin 客户端访问你的媒体库 +要在多种设备上流式播放媒体文件： + +1. 配置 Jellyfin 认证。 + + a. 打开设置，进入**应用** > **Jellyfin** > **入口**。 + + b. 将**认证级别**设置为**内部**。 + + ![设置认证级别](/images/zh/manual/use-cases/jellyfin-auth-level.png#bordered) +2. 下载并安装 [Jellyfin 官方客户端](https://jellyfin.org/downloads/)。 +3. 将客户端连接到 Olares 中的 Jellyfin 服务器。 + + a. 在 Jellyfin 客户端中，自动发现功能会定位到同一网络中的服务器。 + + b. 如果自动发现失败，可手动输入 Olares 提供的服务器地址。 + +4. 使用你的凭据登录 Jellyfin 客户端。 + +:::tip +远程访问媒体库时，请保持专用网络连接处于激活状态，以获得最佳流媒体播放效果。 +:::