From e44e90cb3543e1f47e7711f9ee86184086a996de Mon Sep 17 00:00:00 2001 From: duc <1025434218@qq.com> Date: Fri, 24 Mar 2023 18:14:59 +0800 Subject: [PATCH] wip --- docs/.vitepress/config.ts | 23 +++++- docs/annotations.md | 11 +++ docs/configure.md | 106 +-------------------------- docs/domain.md | 45 ++++++++++++ docs/env.md | 39 ++++++++++ docs/gitserver.md | 27 +++++++ docs/install.md | 148 -------------------------------------- docs/picture.md | 20 ++++++ docs/quick-start.md | 88 +++++++++++++++++++++++ docs/ws.md | 34 +++++++++ docs/yaml-configure.md | 111 ++++++++++++++++++++++++++++ 11 files changed, 396 insertions(+), 256 deletions(-) create mode 100644 docs/annotations.md create mode 100644 docs/domain.md create mode 100644 docs/env.md create mode 100644 docs/gitserver.md delete mode 100644 docs/install.md create mode 100644 docs/picture.md create mode 100644 docs/quick-start.md create mode 100644 docs/ws.md create mode 100644 docs/yaml-configure.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 1ce163833..fb87e7573 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -24,13 +24,30 @@ export default defineConfig({ ] }, { - text: '快速开始', + text: '入门', items: [ - { text: '安装', link: '/install' }, - { text: '配置', link: '/configure' }, + { text: '快速体验', link: '/quick-start' }, { text: '让项目跑起来', link: '/run' }, ] }, + { + text: '配置', + items: [ + { text: '项目全局配置', link: '/configure' }, + { text: '单独分支配置', link: '/yaml-configure' }, + { text: 'annotations', link: '/annotations' }, + { text: '环境变量', link: '/env' }, + ] + }, + { + text: '可用插件', + items: [ + { text: 'git 仓库', link: '/gitserver' }, + { text: '域名', link: '/domain' }, + { text: '登录页背景图', link: '/picture' }, + { text: 'Websocket', link: '/ws' }, + ] + }, { text: 'SDK 接入', items: [ diff --git a/docs/annotations.md b/docs/annotations.md new file mode 100644 index 000000000..fc678938c --- /dev/null +++ b/docs/annotations.md @@ -0,0 +1,11 @@ +--- +title: 注解 +lang: zh-cn +--- + +# Pod 可用注解 + +| name | 类型 | 介绍 | +| ----------------------------------------- | ------------------------ | ----------------------- | +| mars.duc-cnzj.github.io/ignore-containers | string "istio-proxy,app" | 过滤 sidecar 这样的容器 | +| mars.duc-cnzj.github.io/order-index | string "10" | 数值高的在前面 | diff --git a/docs/configure.md b/docs/configure.md index 93e187a80..30ae9f3ba 100644 --- a/docs/configure.md +++ b/docs/configure.md @@ -24,108 +24,4 @@ lang: zh-cn 配好 charts 后保存，会自动加载默认 `values.yaml` 文件，这个只是给你参考用的，然后按照提示配置玩其他字段，其中 `values.yaml` , 有内置变量可以使用，配置完后大概长下面这样 -![配置完其他字段](./images/config4.png) - -## 按分支单独配置 - -用法借鉴 `.gitlab.yml`, 使用时只需要在项目下面创建一个 `.mars.yaml` 就可以了。 - -`.mars.yaml` 配置参考： - -```yaml -# 项目默认的配置文件(可选) -config_file: config.yaml -# 默认配置, 必须用 '|', 全局配置文件，如果没有设置 config_file 则使用这个 -config_file_values: | - env: dev - port: 8000 -# 配置文件的类型(如果有config_file，必填) -config_file_type: yaml -# config_field 对应到 helm values.yaml 中的哪个字段(如果有config_file，必填) -# 可以使用 '->' 指向下一级, 比如：'config->app_name'， 会变成 -# config: -# app_name: xxxx -config_field: conf -# charts 文件在项目中存放的目录(必填), 也可以是别的项目的文件，格式为 "pid|branch|path" -local_chart_path: charts -# 是不是单字段的配置(如果有config_file，必填) -is_simple_env: false -# 若配置则只会显示配置的分支, 默认 "*"(可选) -branches: - dev - - master -# values_yaml 和 helm 的 values.yaml 用法一模一样，但是可以使用变量 -# 目前支持的变量有，使用 `<>` 作为 Delim，避免和内置模板语法冲突 -# `<.ImagePullSecrets>` `<.Branch>` `<.Commit>` `<.Pipeline>` `<.ClusterIssuer>` -# `<.Host1>...<.Host10>` `<.TlsSecret1>...<.TlsSecret10>` -values_yaml: | - # Default values for charts. - # This is a YAML-formatted file. - # Declare variables to be passed into your templates. - - replicaCount: 1 - - image: - repository: xxx - pullPolicy: IfNotPresent - # Overrides the image tag whose default is the chart appVersion. - tag: "<.Branch>-<.Pipeline>" - - imagePullSecrets: [] - nameOverride: "" - fullnameOverride: "" - - ingress: - enabled: false - className: "" - annotations: - kubernetes.io/ingress.class: nginx - kubernetes.io/tls-acme: "true" - cert-manager.io/cluster-issuer: "<.ClusterIssuer>" - hosts: - - host: <.Host1> - paths: - - path: / - pathType: Prefix - tls: - - secretName: <.TlsSecret1> - hosts: - - <.Host1> -``` - - -### 📒 `is_simple_env`, `config_file` 解释 - -::: tip -使用全局配置无需关注这个 -::: - -这是一份普通的 helm charts values.yaml 文件 - -```yaml -# Default values for charts. -# This is a YAML-formatted file. -# Declare variables to be passed into your templates. - -replicaCount: 1 - -image: repository: nginx - pullPolicy: IfNotPresent - tag: "" - -# ... 省略 - -# 你的 app 的 config 配置应该是这样的, 这个 `conf` 字段会被你用到其他地方比如 configmap、secret 等等 -# 下面这个你的 is_simple_env 应该是 false，因为他们都是单独的变量 -# config_file 字段的值是 `conf` -conf: APP_PORT: 8080 - DB_HOST: mysql - DB_PORT: 3306 -#... - -# 下面这个你的 is_simple_env 应该是 true，因为这部分配置是一个整体, config_file 字段的值是 `conf_two` -conf_two: | - APP_PORT: 8080 - DB_HOST: mysql - DB_PORT: 3306 -``` - +![配置完其他字段](./images/config4.png) \ No newline at end of file diff --git a/docs/domain.md b/docs/domain.md new file mode 100644 index 000000000..81c8f06bf --- /dev/null +++ b/docs/domain.md @@ -0,0 +1,45 @@ +--- +title: ingress 域名插件 +lang: zh-cn +--- + +# ingress 域名插件 + +## 同步指定 namespace secret(推荐) + +```yaml +domain_manager_plugin: + name: sync_secret_domain_manager + args: + wildcard_domain: "*.mars.local" + secret_name: "" + secret_namespace: "" +``` + +## 手动配置注入证书 + +```yaml +domain_manager_plugin: + name: manual_domain_manager + args: + wildcard_domain: "*.mars.local" + tls_key: "" + tls_crt: "" +``` + +## cert-manager issue 插件(不推荐) + +```yaml +domain_manager_plugin: + name: cert-manager_domain_manager + args: + wildcard_domain: "*.mars.local" + cluster_issuer: "letsencrypt-mars" +``` + +## default_domain_manager (fake domain) + +```yaml +domain_manager_plugin: + name: default_domain_manager +``` diff --git a/docs/env.md b/docs/env.md new file mode 100644 index 000000000..eed6c291c --- /dev/null +++ b/docs/env.md @@ -0,0 +1,39 @@ +--- +title: 环境变量 +lang: zh-cn +--- + +# 环境变量 + + +| 变量名称 | 介绍 | +| ------------------- | ------------------------------------ | +| <.Branch> | 分支名称，动态: dev/master... | +| <.Commit> | commit sha, 6位 | +| <.Pipeline> | gitlab 流水线id, github 目前获取不到 | +| <.ClusterIssuer> | Cert-manager 的issuer | +| <.Host1-10> | 域名 | +| <.TlsSecret1-10> | 域名对应的secret | +| <.ImagePullSecrets> | 拉取镜像的秘钥 | + + + +```yaml +imagePullSecrets: <.ImagePullSecrets> +image: + tag: "<.Branch>-<.Pipeline>" + +ingress: + enabled: false + annotations: + cert-manager.io/cluster-issuer: <.ClusterIssuer> + hosts: + - host: <.Host1> + paths: + - path: / + pathType: Prefix + tls: + - secretName: <.Secret1> + hosts: + - <.Host1> +``` \ No newline at end of file diff --git a/docs/gitserver.md b/docs/gitserver.md new file mode 100644 index 000000000..ec97052f0 --- /dev/null +++ b/docs/gitserver.md @@ -0,0 +1,27 @@ +--- +title: Git 仓库 +lang: zh-cn +--- + +# Git 仓库 + +## gitlab(推荐) + +```yaml +git_server_plugin: + name: gitlab + args: + token: "" + baseurl: "https://gitlab.com/api/v4" +``` + +## github + +> github 接口不太好用，集成较差，无法使用 `pipeline` 变量 + +```yaml +git_server_plugin: + name: github + args: + token: "" +``` \ No newline at end of file diff --git a/docs/install.md b/docs/install.md deleted file mode 100644 index 485ba2dd2..000000000 --- a/docs/install.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: 安装 -lang: zh-cn ---- - -# 安装 - -::: tip -安装 mars 使用 二进制安装/helm 安装(推荐)。 -::: - -## 二进制安装 - -直接去 [release page](https://github.com/DuC-cnZj/mars/releases) 下载二进制包，然后执行 - -```bash -mars init -vim config.yaml -``` - -需要手动配置的参数 - -```yaml -app_port: 6000 -#grpc_port: 50000 -debug: false - -# use app show tags -# eg: cron,api,metrics -#exclude_server: "" - -# 'logrus' | 'zap' -#log_channel: "logrus" - -# 开启 git 请求缓存，默认开启，因为 git 请求比较慢，需要缓存 -git_server_cached: true - -# 'db' or 'memory' -cache_driver: "memory" - -git_server_plugin: - name: gitlab - args: - token: "" - baseurl: "https://gitlab.com/api/v4" -# name: github -# args: -# token: "" -ws_sender_plugin: - name: ws_sender_memory -# name: ws_sender_nsq -# args: -# addr: 127.0.0.1:4150 -# lookupd_addr 可选，有就用 -# lookupd_addr: 127.0.0.1:4160 -# name: ws_sender_redis -# args: -# addr: 127.0.0.1:6379 -# password: "" -# db: 1 -domain_manager_plugin: - name: default_domain_manager -# name: manual_domain_manager -# args: -# wildcard_domain: "*.mars.local" -# tls_key: "" -# tls_crt: "" -# name: sync_secret_domain_manager -# args: -# wildcard_domain: "*.mars.local" -# secret_name: "" -# secret_namespace: "" -# name: cert-manager_domain_manager -# args: -# wildcard_domain: "*.mars.local" -# cluster_issuer: "letsencrypt-mars" -picture_plugin: - name: picture_cartoon -# name: picture_bing - -# kubeconfig 如果在集群外部，则需要配置，否则不用 -kubeconfig: "" - -# upload_dir 默认是 /tmp/mars-uploads -upload_dir: "" - -# 默认 50m, 使用 MB,Gi,m,g这样的写法 -#upload_max_size: "50m" - -# 文件上传到 s3 -s3_endpoint: "" -s3_access_key_id: "" -s3_secret_access_key: "" -s3_use_ssl: false -s3_bucket: mars - -# database -# 'sqlite' or 'mysql', 如果是 'sqlite', 'db_database' 为 db 绝对路径 -db_driver: "sqlite" -db_database: /tmp/mars-sqlite.db -# 如果是 'mysql' 以下均为必填项，如果是 'sqlite' 就不用填 -db_host: 127.0.0.1 -db_port: 3306 -db_username: root -db_password: "" -db_slow_log_enabled: true -# "ns", "us" (or "µs"), "ms", "s", "m", "h" -db_slow_log_threshold: 200ms - -jaeger_agent_host_port: "" - -# 集群外网访问 ip -external_ip: "127.0.0.1" - -install_timeout: 90s - -# imagepullsecrets: docker 私有镜像仓库需要配置相关的账号密码以及仓库地址 -# server default: "https://index.docker.io/v1/" -imagepullsecrets: - - username: "jack" - password: "12345" - email: "jack@example.com" - # server: "" - - username: "john" - password: "12345" - email: "john@example.com" - server: "registry.cn-hangzhou.aliyuncs.com" - -oidc: - - name: "sso1" - enabled: true - provider_url: "http://127.0.0.1:9001" - client_id: "sso-xxx" - client_secret: "xxxx" - redirect_url: "http://127.0.0.1:3000/auth/callback" - -admin_password: "123456" -private_key: "" - -``` - -## helm 安装（推荐） - -```bash -helm repo add mars-charts https://duc-cnzj.github.io/mars-charts/ -# 这里需要自行配置相关参数和上面一样 -helm show values mars-charts/mars > mars-values.yamlhelm upgrade --install mars mars-charts/mars -f mars-values.yaml -``` \ No newline at end of file diff --git a/docs/picture.md b/docs/picture.md new file mode 100644 index 000000000..0fed6b2b5 --- /dev/null +++ b/docs/picture.md @@ -0,0 +1,20 @@ +--- +title: 登录页背景图插件 +lang: zh-cn +--- + +# 登录页背景图插件 + +## 动漫图片 + +```yaml +picture_plugin: + name: picture_cartoon +``` + +## 风景图 + +```yaml +picture_plugin: + name: picture_bing +``` \ No newline at end of file diff --git a/docs/quick-start.md b/docs/quick-start.md new file mode 100644 index 000000000..3882de86e --- /dev/null +++ b/docs/quick-start.md @@ -0,0 +1,88 @@ +--- +title: 快速体验 +lang: zh-cn +--- + +# 安装 + +::: tip +本页教程为了让用户快速入门，采用使用二进制安装的方法，单机部署，如果要高可用部署，以及的更多功能，请看文档。 +::: + +## 二进制安装 + +直接去 [release page](https://github.com/DuC-cnZj/mars/releases) 下载二进制包，然后执行 + +```bash +./mars init +vim config.yaml + +# Output: +# 2023/03/24 16:08:54 创建成功！ +``` + +参数复制这份, 其中 `kubeconfig`、gitlab `token`、`external_ip` 这3项需要配置 + +```yaml +kubeconfig: "" # TODO 配置集群 kubeconfig 的绝对路径 +app_port: 6000 +git_server_plugin: + name: gitlab + args: + token: "" # TODO 需要自行创建 gitlab 仓库 read 权限的 token + baseurl: "https://gitlab.com/api/v4" +ws_sender_plugin: + name: ws_sender_memory +domain_manager_plugin: + name: default_domain_manager +picture_plugin: + name: picture_cartoon +db_driver: "sqlite" +db_database: /tmp/mars-sqlite.db +# TODO 写 nodePort 能访问到的 ip +external_ip: "127.0.0.1" +imagepullsecrets: [] +admin_password: "123456" +private_key: |- + -----BEGIN RSA PRIVATE KEY----- + MIICWwIBAAKBgQCdx5ZBeL3P3lH2fU/8yd4E1L880DjaKCnnnQkya+kOE7kkJNtP + xW4WIKsBgXUPtXUYk/uA5AkklJ/1ssiTbkM/G5J54ThsACarhiNijUznD81c7g0Q + 6pbHYGAHU91wQgpcIv39cOKZVpFkEfIwgBMIKUvupBpGyXMU4YALVV23CQIDAQAB + AoGARo+kzeDumlDlvONr6zRoOybd45eHZWEC5JchLtB9qJL/gH+PKQy1X+X6NDEu + JflTxcsgdhMFV7u0EdCDzRNJtPKP/cU8hww0J2l3ZKTGzbbQnLIBFD3In8sEc9xe + 3ikEjqs0EgSh3uY5XEq8qzuX3cI+FNlGyOwzM+ZcN7nWfPUCQQDOURX82COQIfAT + RjTshDQ55J/DUPPHyzpTER9OZNXYKp0IBBNzYyhJ6SHQHSuxHfL8W1FVHhmIsIBW + GQWo0y7zAkEAw8ZPJ4QH5otMsIgIfwMuPX0rO+QxwmJ6eg9ADuFr5zv6HizjAVVP + dKXuUU0gnemD4DncgiV2jZ0v2RzHK1aZEwJAR6G7gpgAcPB3jBmaEmwsPdV06rlW + io2y6FhPiEZWQME62CeiITPSLyc0SC94lfwR+zAxYt4ae2zcgggaAO2hpQJAecA5 + d7S3iRu2XM6sofijaCAQpBV9EItX6dLUHqz4Av0cxmlZ33ljiYKr3CngD/SqS+cQ + CGwt91H68MXh40TeuwJARxz1VMLq7hKo8J4scAW/YrBTE4N6malYjYoR2HFs+YwL + cSE/4A4yfzTjN2r5GuJr8rTU7gU4Su9C8dLC0htWCA== + -----END RSA PRIVATE KEY----- +``` + +## 启动 mars + +```bash +./mars serve + +# 打开 localhost:6000 +``` + +账号: `admin`, 密码: `123456` + +## 配置 + +1. [fork 到你自己的 gitlab 仓库](https://gitlab.com/DuC-cnZj/mars-demo), 然后回到 mars +2. mars 页面右上角点击`管理员` +3. 点击`项目配置`进入项目管理页面 +4. 搜索 `mars-demo`, 点击`开启` + +## 部署 demo + +1. 回到主页，点击右上角 + 创建空间 +2. 在空间里部署 demo 项目 + +## 故障排除 + +> 任何问题请联系 qq: 1025434218 \ No newline at end of file diff --git a/docs/ws.md b/docs/ws.md new file mode 100644 index 000000000..6f700d0a0 --- /dev/null +++ b/docs/ws.md @@ -0,0 +1,34 @@ +--- +title: Websocket 插件 +lang: zh-cn +--- + +# Websocket 插件 + +## memory (单机) + +```yaml +ws_sender_plugin: + name: ws_sender_memory +``` + +## redis + +```yaml +ws_sender_plugin: + name: ws_sender_redis + args: + addr: 127.0.0.1:6379 + password: "" + db: 1 +``` + +## nsq (大规模) + +```yaml +ws_sender_plugin: + name: ws_sender_nsq + args: + addr: 127.0.0.1:4150 + lookupd_addr: 127.0.0.1:4160 +``` diff --git a/docs/yaml-configure.md b/docs/yaml-configure.md new file mode 100644 index 000000000..abce4b1c5 --- /dev/null +++ b/docs/yaml-configure.md @@ -0,0 +1,111 @@ +--- +title: 开启单独分支配置 +lang: zh-cn +--- + +# 开启单独分支配置 + +## 按分支单独配置 + +用法借鉴 `.gitlab.yml`, 使用时只需要在项目下面创建一个 `.mars.yaml` 就可以了。 + +`.mars.yaml` 配置参考： + +```yaml +# 项目默认的配置文件(可选) +config_file: config.yaml +# 默认配置, 必须用 '|', 全局配置文件，如果没有设置 config_file 则使用这个 +config_file_values: | + env: dev + port: 8000 +# 配置文件的类型(如果有config_file，必填) +config_file_type: yaml +# config_field 对应到 helm values.yaml 中的哪个字段(如果有config_file，必填) +# 可以使用 '->' 指向下一级, 比如：'config->app_name'， 会变成 +# config: +# app_name: xxxx +config_field: conf +# charts 文件在项目中存放的目录(必填), 也可以是别的项目的文件，格式为 "pid|branch|path" +local_chart_path: charts +# 是不是单字段的配置(如果有config_file，必填) +is_simple_env: false +# 若配置则只会显示配置的分支, 默认 "*"(可选) +branches: - dev + - master +# values_yaml 和 helm 的 values.yaml 用法一模一样，但是可以使用变量 +# 目前支持的变量有，使用 `<>` 作为 Delim，避免和内置模板语法冲突 +# `<.ImagePullSecrets>` `<.Branch>` `<.Commit>` `<.Pipeline>` `<.ClusterIssuer>` +# `<.Host1>...<.Host10>` `<.TlsSecret1>...<.TlsSecret10>` +values_yaml: | + # Default values for charts. + # This is a YAML-formatted file. + # Declare variables to be passed into your templates. + + replicaCount: 1 + + image: + repository: xxx + pullPolicy: IfNotPresent + # Overrides the image tag whose default is the chart appVersion. + tag: "<.Branch>-<.Pipeline>" + + imagePullSecrets: [] + nameOverride: "" + fullnameOverride: "" + + ingress: + enabled: false + className: "" + annotations: + kubernetes.io/ingress.class: nginx + kubernetes.io/tls-acme: "true" + cert-manager.io/cluster-issuer: "<.ClusterIssuer>" + hosts: + - host: <.Host1> + paths: + - path: / + pathType: Prefix + tls: + - secretName: <.TlsSecret1> + hosts: + - <.Host1> +``` + + +### 📒 `is_simple_env`, `config_file` 解释 + +::: tip +使用全局配置无需关注这个 +::: + +这是一份普通的 helm charts values.yaml 文件 + +```yaml +# Default values for charts. +# This is a YAML-formatted file. +# Declare variables to be passed into your templates. + +replicaCount: 1 + +image: repository: nginx + pullPolicy: IfNotPresent + tag: "" + +# ... 省略 + +# 你的 app 的 config 配置应该是这样的, 这个 `conf` 字段会被你用到其他地方比如 configmap、secret 等等 +# 下面这个你的 is_simple_env 应该是 false，因为他们都是单独的变量 +# config_file 字段的值是 `conf` +conf: + APP_PORT: 8080 + DB_HOST: mysql + DB_PORT: 3306 +#... + +# 下面这个你的 is_simple_env 应该是 true，因为这部分配置是一个整体, config_file 字段的值是 `conf_two` +conf_two: | + APP_PORT: 8080 + DB_HOST: mysql + DB_PORT: 3306 +``` +